---
name: "containers-auth.json"
section: "5"
platform: "linux"
package: "containers-common"
version: "1:0.69.2-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/containers-auth.json"
---

# containers-auth.json(5)

syntax for the registry authentication file

## NAME

containers-auth.json - syntax for the registry authentication file

## DESCRIPTION

A file in JSON format controlling authentication against container image registries. The primary (read/write) file is stored at **${XDG\_RUNTIME\_DIR}/containers/auth.json** on Linux; on Windows and macOS, at **$HOME/.config/containers/auth.json**.

When searching for the credential for a registry, the following files will be read in sequence until the valid credential is found: first reading the primary (read/write) file, or the explicit override using an option of the calling application. If credentials are not present there, the search continues in **${XDG\_CONFIG\_HOME}/containers/auth.json** (usually **~/.config/containers/auth.json**), **$HOME/.docker/config.json**, **$HOME/.dockercfg**.

Except for the primary (read/write) file, other files are read-only unless the user, using an option of the calling application, explicitly points at it as an override.

## FORMAT

The auth.json file stores, or references, credentials that allow the user to authenticate to container image registries. It is primarily managed by a **login** command from a container tool such as **podman login**, **buildah login**, or **skopeo login**.

Each entry contains a single hostname (e.g., **docker.io**) or a namespace (e.g., **quay.io/user/image**) as a key, and credentials in the form of a base64-encoded string as value of **auth**. The base64-encoded string contains a concatenation of the username, a colon, and the password.

When checking for available credentials, the relevant repository is matched against available keys in its hierarchical order, going from most-specific to least-specific. For example, an image pull for **my-registry.local/namespace/user/image:latest** will result in a lookup in **auth.json** in the following order:

- •

  **my-registry.local/namespace/user/image**

- •

  **my-registry.local/namespace/user**

- •

  **my-registry.local/namespace**

- •

  **my-registry.local**

This way it is possible to setup multiple credentials for a single registry which can be distinguished by their path.

The following example shows the values found in auth.json after the user logged in to their accounts on quay.io and docker.io:

```
{
	"auths": {
		"docker.io": {
			"auth": "erfi7sYi89234xJUqaqxgmzcnQ2rRFWM5aJX0EC="
		},
		"quay.io": {
			"auth": "juQAqGmz5eR1ipzx8Evn6KGdw8fEa1w5MWczmgY="
		}
	}
}
```

This example demonstrates how to use multiple paths for a single registry, while preserving a fallback for **my-registry.local**:

```
{
	"auths": {
		"my-registry.local/foo/bar/image": {
			"auth": "…"
		},
		"my-registry.local/foo": {
			"auth": "…"
		},
		"my-registry.local": {
			"auth": "…"
		},
	}
}
```

An entry can be removed by using a **logout** command from a container tool such as **podman logout** or **buildah logout**.

In addition, credential helpers can be configured for specific registries, and the credentials-helper software can be used to manage the credentials more securely than storing only base64-encoded credentials in **auth.json**.

When the credential helper is in use on a Linux platform, the auth.json file would contain keys that specify the registry domain, and values that specify the suffix of the program to use (i.e. everything after docker-credential-).  For example:

```
{
    "auths": {
        "localhost:5001": {}
    },
    "credHelpers": {
		"registry.example.com": "secretservice"
	}
}
```

For more information on credential helpers, please reference the GitHub docker-credential-helpers project ⟨https://github.com/docker/docker-credential-helpers/releases⟩.

## SEE ALSO

```
buildah-login(1), buildah-logout(1), podman-login(1), podman-logout(1), skopeo-login(1), skopeo-logout(1)
```

## HISTORY

Feb 2020, Originally compiled by Tom Sweeney tsweeney@redhat.com ⟨mailto:tsweeney@redhat.com⟩