Podman Add Registry: 2 Easy Way

Estimated reading time: 5 minutes

Last updated on October 28th, 2024 at 12:24 am

Podman is a container management engine that allows you to run and manage the container securely. To run the containers, you need the container image to come from the container registries like DockerHub or private registries.

By default, Podman ships with a limited public registry list that allows you to pull and run the containers. Using the private registry or other than the default list, you need to add it under the registry.conf file

Let’s explore “Podman Add Registry” to add more registries to use a wide range of container images in your workflow.

Docker Push Image to Remote Registry Made EASY -⏱️ 5-Minute!

Podman Pull Docker Image: Easier Than You Think!

Why Add Podman Registry?

Podman comes with a pre-populated list of public registries like DockerHub allows you to pull container images after the installation. If you only use the publicly available images, you might not need to add an extra Podman registry.

But there are particular use cases where you need to add the Podman registry:

1. Private Registry

Public registries like DockerHub or quay.io provide a vast selection of ready-to-use software. An application, developed within your organization is not publicly available therefore you need a private registry.

2. Regional Mirror

A regional mirror can significantly improve the container image download speed rather than relying on the official public registry.

For both of the mentioned reasons you need “Podman add registry”. Let’s explore how to add a Podman registry.

Podman Cheat Sheet

FREE Podman Cheat Sheet (Everything You Need, In One Place)

This is the last Podman Cheat Sheet you’ll ever need. Why?
Because it’s not just a list of commands—it’s a shortcut to make your work easier, faster, and more effective.

Stop wasting time digging through documentation. With this cheat sheet, you’ll get exactly what you need, right when you need it.

Podman Add Registry

Before you add the Podman registry, you need two important pieces of information:

Registry & Authentication Information

Registry URL: You need the address of the registry, like docker.io, quay.io or your-private-registry.info

Authentication: Private registries often need authentication credentials such as username and password or service account access token.

Before You Start Get Below Details:
  • Registry URL
  • Username
  • Password or Access Token

System-Wide Podman Add Registry

Podman uses the registry configuration file to modify the default registry information. Modify the registry.conf allow the system-wide Podman registry.

Podman Container Configuration File: 5 Hidden Hacks

You need administration access to modify the registries.conf. You can modify the user-specific information with the HOMEDIR configuration

1. Locate the registry.conf

You can find them registry.conf under the /etc/containers/registries.conf location and for user-specific $HOME/.config/containers/registries.conf

  1. /etc/containers/registries.conf
  2. $HOME/.config/containers/registries.conf
2. Edit the file

Edit the registry.conf file with vim or nano with sudo privileges

Bash
# System-Wide configuration
nano /etc/containers/registries.conf

# User-Specific configuration
nano $HOME/.config/containers/registries.conf
3. Add the registry

Podman uses the TOML-type configuration, you can add each registry under the registries.conf

Bash
[[registry]]
location=quay.io

If you have the private registries with authentication:

Bash
[[registry]]
location="my-registry.tld"
username="username"
password="password"

Single Use Podman Add Registry

You can modify the registry information for the single session use with this. You don’t need administrator privileges for this:

1. Open terminal
2. Use the podman login command:
Bash
podman login  -u username -p password registry_url

Replace the registry_url, username and password with the actual details:

Bash
podman login -u devtodevops -p devtodevops quai.io
Podman Cheat Sheet

FREE Podman Cheat Sheet (Everything You Need, In One Place)

This is the last Podman Cheat Sheet you’ll ever need. Why?
Because it’s not just a list of commands—it’s a shortcut to make your work easier, faster, and more effective.

Stop wasting time digging through documentation. With this cheat sheet, you’ll get exactly what you need, right when you need it.

Advanced: Podman Add Registry

I have covered the common case for “Podman Add Registry”, but in many cases, you need some advanced configuration.

Add Insecure Registry

Adding an Insecure registry is straightforward, you can follow the same method as editing the registries.conf file with an extra flag insecure=true

Bash
[[registry]]
location="localhost:5000"
insecure=true

You can also use the --tls-verify=false flag with the podman login command for a single session

Bash
podman login --tls-verify=false -u devtodevops -p devtodevops localhost:5000

Login Succeeded!

Trusting Self-Signed Certificate

If you have the private registries that use the self-signed certificate, you can use the podman login command with the --cert-dir option:

Bash
podman login --cert-dir /etc/containers/certs.d/ -u devtodevops -p devtodevops localhost:5000

Login Successed!

Podman Verify the Registry Setup:

Once the registry configuration is set up, let’s verify the setup by pulling the image from that registry.

1. Get the Private Image Name

Get the name of your image from the private registry that looks like this:

  • quay.io/my-repository/devtodevops
  • ghcr.io/my-repository/devtodevops
  • my-registry.tld/my-repository/devtodevops
2. Pull the Private Image

You should use the fully qualified image name to pull the container image.

Bash
podman pull my-registry.tld/my-repository/devtodevops
3. Push the Private Image

Now let’s verify by pushing the image to the private registry:

Bash
podman build -t my-registry.tld/my-repository/devtodevops .

podman push my-registry.tld/my-repository/devtodevops

If you don’t want to use the full qualified image name, I wrote about using the Podman Unqualified Search Registries.

Additional Reading

Podman Pull Docker Image: Easier Than You Think!

Podman Container Image Update: Secure them in Seconds!

Podman Container Configuration File: 5 Hidden Hacks

Podman Cheat Sheet

FREE Podman Cheat Sheet (Everything You Need, In One Place)

This is the last Podman Cheat Sheet you’ll ever need. Why?
Because it’s not just a list of commands—it’s a shortcut to make your work easier, faster, and more effective.

Stop wasting time digging through documentation. With this cheat sheet, you’ll get exactly what you need, right when you need it.

Kashyap Merai
Kashyap Merai

Kashyap Merai, a Certified Solution Architect and Public Cloud Specialist with over 7 years in IT. He helped startups in Real Estate, Media Streaming, and On-Demand industries launch successful public cloud projects.

Passionate about Space, Science, and Computers, He also mentors aspiring cloud engineers, shaping the industry's future.

Connect with him on LinkedIn to stay updated on cloud innovations.