How to Login to Docker Hub and Private Registries … – How-To Geek

Docker login

Video Docker login


A new Docker installation uses public interactions with Docker Hub by default. Logging in allows you to access your private content and benefit from less restrictive Docker API speed limits.

In this guide, we’ll show how to log into the Docker CLI, covering both Docker Hub authentication and your own private records. We’ll also look at some of the common issues with storing Docker credentials.


into Docker Hub

Logging into Docker Hub allows the Docker CLI to access private content accessible to your account. It will also give you the higher rate limit threshold of 200 image extracts per six hours, instead of the 100 extracts per six hours offered to unauthenticated clients.

Use the docker login command

to provide your credentials and authenticate with the server: $ docker login

Username: Password:

You will be asked to enter your username and password interactively. Docker will attempt to log in to Docker Hub with the credentials. You’ll see Successful sign-in if the details are accepted. Docker will store the issued authentication token in the .docker/config.json file.

$ docker login Login Successful access tokens

for 2FA logins

Docker Hub accounts with two-factor authentication enabled must use an access token instead of a password. Using the Docker Hub web UI, click your profile icon at the top right and choose “Account Settings” from the menu. Use the left sidebar to switch to the “Security” tab.

<img src="" alt="Docker

Hub access token creation image” />

Click the blue “New Access Token” button to create a personal access token. Be careful to write down the token key that is displayed, as you will not be able to retrieve it in the future. Use this token instead of your normal password when you run docker login again in the CLI.

Non-interactive logins

You can provide your user name and password as command-line prompts:

$ docker login -username demo -password

example This is useful when you log in programmatically or as part of a CI pipeline. To increase security, use the -password-stdin flag to instruct Docker to read the STDIN password. This allows you to pipe a password file, preventing plain text from being captured in shell history and CI job logs.

$ cat password.txt | docker login -username demo -password-stdin


into private records

docker login also allows you to log in to self-hosted records. Provide the registry host name and port as the first argument to the command. Docker Hub is always used when no argument is given.

$ docker login Username: Password:

You can still use the -username, -password, and -password-stdin flags when working with custom records. You can log in to multiple records simultaneously: repeat the docker login command as many times as you need.

Add credentials


Sometimes, you might want to manually log in to a registry by adding an existing authentication token to the Docker configuration file. This can be useful in CI environments where you want to provide a previously obtained token as a pipeline variable.

You can add authentication tokens yourself by editing their .docker/config.json file. Add a new key for your record inside the auths field at the top of the file. Provide an object as the key value; This object needs a single Auth property that contains the token. Here’s an example for the registry:

You can add a Docker Hub token using as the registry URL


Multiple accounts for one record A

significant limitation of the authentication mechanism is its requirement that records be mapped one-to-one with user accounts. It is not possible to log on simultaneously with multiple users in the same registry. This is usually desirable when using a private record that separates permissions on projects or teams.

You can mitigate the problem by splitting your credentials into multiple configuration files. The Docker CLI uses the -config flag or DOCKER_CONFIG environment variable to determine which file to upload for each invocation.

# Authenticate as user-1$ docker -config ~/docker/user-1.conf login -username user-1 -password foobar # Authenticate as user-2$ docker -config ~/docker/user-2.conf login -username user-2 -password foobar # Extract an image from as user-1$ docker -config ~/docker/user-1.conf pull my-team/my-project:latest # Push an image to as user-2$ docker -config ~/docker/user-2.conf push my-team/my-project:latest When you

have many projects to work with, you can use an alias or shell function to rewrite Docker in a command that automatically selects the correct configuration file for your working directory. alias

docker=”docker -config ~/docker/$(basename $PWD).conf $1″

Credential Helpers

Docker stores your credentials insecurely in ~/.docker/config.json by default. You can add more protection by integrating a credential helper utility. Enabled helpers can handle credential storage, get and delete commands issued by Docker in response to CLI operations.

You can associate a record with a particular helper utility by using the credHelpers field

in the configuration file:

This example uses the pass credential helper to store the credentials in Pass instead of the configuration file. The Pass helper is provided as part of Docker’s docker-credential-helpers package that also includes integrations with macOS Keychain, Windows Credential Manager, and D-Bus Secret Service.


out You can log out

You can log out by manually deleting the registry section of the .docker/config.json file or by using the docker logout command.

$ docker

logout Like docker login, logouts are directed to Docker Hub by default. You can log out of a private record by passing its hostname as the only argument to the command:

$ docker logout

Common Issues

Most Docker authentication issues stem from missing or invalid credentials. If you have logged in before but authentication does not work, try logging out and logging back in:

$ docker logout # OR $ docker logout $ docker login # OR $ docker login

Systematically declined credentials could indicate a problem with your registration account. For Docker Hub, verify that you’ve followed the instructions above to use a personal access token instead of a password with accounts protected by 2FA.

Confusion can also occur when you have multiple Docker configuration files. Check that you are using the -config flag or DOCKER_CONFIG environment variable to load the correct one every time you push and extract your images.


Getting the Docker

CLI connected to your Docker Hub account or a private registry is usually best handled using the docker login command. You can provide credentials interactively, as flags, or through a pipelined password file. Be sure to use a personal access token instead of your password if you have two-factor authentication enabled.

Although there is perfect support for authenticating to multiple records, working with multiple accounts in one registry is more cumbersome. Try to use separate configuration files whenever possible, or configure the registry with specially defined user accounts appropriate for each of your environments.

Contact US