podman-login

Log in to a registry (non-persistent on Linux; persistent on Windows/macOS)

$ podman login [registry.example.org]

$ podman login --authfile $HOME/.config/containers/auth.json [registry.example.org]

$ podman login --tls-verify=false [registry.example.org]

podman login [options] [registry]

--authfile=
    Specify a custom path to the authentication file to use. This overrides the default location.

--cert-dir=
    Provide a path to client certificates for TLS authentication with the registry. This is useful for registries requiring client-side certificates.

--get-login
    Retrieve login credentials from the authentication file without performing a new login. This can be useful for scripting purposes to check existing login status.

--help
    Display a brief help message for the command and exit.

--no-hosts
    Prevent the registry from being added to the system's registries configuration file (/etc/containers/registries.conf or user-specific files). This can be useful for one-time logins.

-p, --password=
    Provide the password for authentication directly on the command line. Note: Using this option is generally insecure as the password might be exposed in shell history or process listings. It is recommended to let Podman prompt for the password interactively.

--tls-verify=
    Require TLS verification when connecting to the registry. The default value is true. Set to false to disable TLS certificate verification (not recommended for production).

-u, --username=
    Provide the username for authentication to the registry.

The podman-login command is used to authenticate Podman to a specified container registry. This authentication allows you to securely pull and push container images to and from private or protected registries. When invoked without a specific registry URL, it attempts to log into the default Docker Hub registry (docker.io). Credentials, once successfully entered, are typically stored in an authentication file (e.g., containers-auth.json, often found in your XDG runtime directory or user configuration directory). This stored authentication information is then used by subsequent Podman commands like podman pull or podman push for operations requiring registry access. It is an essential command for managing container images in secure, enterprise-level environments or when working with custom private registries.

Providing the password directly on the command line using the -p or --password option is highly insecure. This method may expose your credentials in shell history, logs, or process listings. It is strongly recommended to omit the password argument and allow podman-login to interactively prompt you for it, which is the more secure approach.

Login credentials are saved in a JSON-formatted authentication file (typically named containers-auth.json) within your user's configuration directory (e.g., ~/.config/containers/auth.json) or the XDG runtime directory. This file stores encrypted credentials for future Podman operations.

If no registry argument is provided to podman-login, the command defaults to authenticating against docker.io, which is the official Docker Hub registry.

For enhanced security, if the password is not supplied via command-line options (e.g., -p), podman-login will interactively prompt the user to enter the password. This prevents the password from being recorded in shell history or being visible in process lists.

After a successful login, credentials are saved in a JSON file, typically located at $XDG_RUNTIME_DIR/containers/auth.json or ~/.config/containers/auth.json. Podman automatically references this file for subsequent authenticated operations like pulling or pushing images.

podman-login is an integral part of the Podman project, which emerged as an open-source, daemonless alternative to Docker for managing OCI containers and pods on Linux systems. Developed with a focus on security and integration with standard Linux tools, Podman aimed to provide a familiar command-line experience. The login command has been a core capability since Podman's early development, enabling users to interact seamlessly with various container registries, which is fundamental for image distribution and management in modern containerized workflows.

podman(1), podman-logout(1), podman-pull(1), podman-push(1), containers-auth.json(5), registries.conf(5)