Podman 6 Configuration File Changes

Announcement, Blog, Buildah, Podman, Releases, Skopeo

Podman 6 Configuration File Changes

June 22, 2026

Paul Holzinger

Podman 6 is about to be released soon, so I would like to talk about the biggest change we made: a major rework of how we handle and parse our configuration files. This does not just affect Podman but also Buildah, Skopeo, and many other tools building on top of our underlying go.podman.io/image and go.podman.io/storage libraries.

The following files or locations are affected by this rework:

containers.conf

registries.conf

storage.conf

policy.json

registries.d

certs.d

History

Before diving into the details on what changed, let us have a look at why we felt the need to do this. While Podman is a large application, we do also maintain our other tools such as Buildah and Skopeo. They do similar things, for example, pull an image; so there is a strong need for code sharing across our tools. To facilitate that, we use the go.podman.io/storage (used to be known as containers/storage), go.podman.io/image (used to be known as containers/image) and go.podman.io/common (used to be known as containers/common) go libraries, which are now part of container-libs project.

Now I wasn’t around in the early days of the project but the fact is that Podman is our newest application given that both Skopeo and Buildah were created before it. The storage and registry libraries were created before Podman as well. Digging a bit into our git history I found the first storage.conf addition was in May 2017 and the first registries.conf addition in August 2017.

The first commit in the Podman repo is from November that same year.

Based on that and the fact that these projects all were in its early days, I can assume the focus was just to have something working. In the early days there was not even yet rootless support which means the config files did not account for that initially either. These things were added on top later and so started a long time adding specific features to specific files.

One problem was that the config file lived in different repositories using different code to parse the files, so over time they diverged more and more and got different rules with weird special cases.

For example because storage.conf contains the storage paths, graphroot and runroot, which had to be set there they point to a root owned place such as /var/lib/containers. That then made it impossible for a rootless user to use these paths so storage.conf opted for a rule to not read these fields in the /etc/containers/storage.conf location and just rely on user configuration in ~/.config/containers/storage.conf. But then administrators also wanted to set a global default path for all users so a rootless_storage_path was added which was read in the /etc location so we ended up with complicated logic to parse only certain fields in certain contexts.

Over the years we also got other demands, support for having the config file in /usr/share/containers. This support was added to some but not all files, simply because adding across many repos would have been a lot of work so often things were only fixed in places where we had user requests but not consistently for other files.

Ultimately we ended up with a lot of code scattered across three repositories and many differences. This resulted not just in problems for our users but also us maintainers as we needed to learn 3+ different parsing rules. Every time someone asked me how/where to set option X, I had to check what special cases exist for this file.

One thing that helped here is that we integrated our three libraries (storage, image and common) into a single monorepository last year which allowed us to make changes across all of them more efficiently.

With Podman 6 on the horizon and many user issues about various small things in regard to our different config files, we decided it is time to solve this and unify the behaviors and make them share code to reduce tech debt.

Given that some config files just have different and conflicting behaviors it means that there was really no way to avoid some breaking changes so waiting for the major release was the logical choice.

Goals

The main aim of the changes is to unify the config file parsing experience. Instead of using a different set of config file locations, .i.e. some supported /usr/share/containers others did not, we like to have the same set of search locations across all files. In particular, adding support for /usr/share/containers means packagers can deliver the config file there and administrators can use /etc/containers without having to deal with package conflicts on upgrades.

There are also various new use cases we wanted to solve. We often have asks from admins that they want to configure certain config options only for all users but not root or the other way around. If /etc/containers/registries.conf is read for all users that is of course not...