How to Push a Docker Image to Docker Hub (Step-by-Step Guide)

Docker Hub is the world’s largest public registry for container images. Pushing your own images there makes it easy to share them with teammates, deploy them to servers, or use them in CI/CD pipelines. In this guide, you’ll learn exactly how to push a Docker image to Docker Hub, from creating your account to verifying the upload.

What You Need Before You Start

Before pushing an image to Docker Hub, make sure you have Docker installed on your machine (Docker Desktop on Windows or macOS, or Docker Engine on Linux), a free Docker Hub account from hub.docker.com, and a Docker image you’ve built locally or a Dockerfile to build one.

You can confirm Docker is installed by running:

bash

docker --version

Step 1: Create a Repository on Docker Hub (Optional)

Log in to Docker Hub, click Create repository, give it a name (for example, my-app), and choose whether it should be public or private.

This step is optional. If the repository doesn’t exist, Docker Hub will create it automatically the first time you push, and it will be public by default. Creating it manually first gives you control over visibility and description.

Step 2: Log In to Docker Hub from the Terminal

Authenticate your local Docker client with your Docker Hub account:

bash

docker login

Enter your Docker Hub username and password when prompted. If you see Login Succeeded, you’re ready to go.

Security tip: Instead of your account password, use a Personal Access Token. Generate one in Docker Hub under Account Settings → Personal access tokens, then log in with:

bash

echo "YOUR_ACCESS_TOKEN" | docker login -u YOUR_USERNAME --password-stdin

This is the recommended approach for CI/CD pipelines and accounts with two-factor authentication enabled.

Step 3: Build Your Docker Image

If you don’t already have an image, build one from your project directory containing a Dockerfile:

bash

docker build -t my-app .

List your local images to confirm it was created:

bash

docker images

Step 4: Tag the Image for Docker Hub

Docker Hub requires images to follow the naming format username/repository:tag. Tag your local image accordingly:

bash

docker tag my-app yourusername/my-app:1.0

Here, yourusername is your Docker Hub username, my-app is the repository name, and 1.0 is the version tag. If you omit the tag, Docker uses latest by default.

It’s good practice to push both a version tag and latest:

bash

docker tag my-app yourusername/my-app:latest

You can also skip this step by building with the correct name from the start:

bash

docker build -t yourusername/my-app:1.0 .

Step 5: Push the Image to Docker Hub

Now push your tagged image:

bash

docker push yourusername/my-app:1.0

Docker uploads the image layer by layer. Layers that already exist on Docker Hub are skipped, which makes subsequent pushes much faster. To push the latest tag too:

bash

docker push yourusername/my-app:latest

To push all tags of a repository at once:

bash

docker push --all-tags yourusername/my-app

Step 6: Verify the Push

Go to your Docker Hub dashboard and open the repository. You should see your tags listed along with their size and push time.

You can also test it by pulling the image on another machine:

bash

docker pull yourusername/my-app:1.0

Common Errors and How to Fix Them

“denied: requested access to the resource is denied” is the most common error. It usually means the image isn’t tagged with your Docker Hub username, you’re not logged in, or you’re pushing to a repository you don’t own. Double-check your tag with docker images and run docker login again.

“An image does not exist locally with the tag” means the tag in your push command doesn’t match any local image. Run docker images and make sure the name and tag match exactly.

“unauthorized: authentication required” means your session expired or your credentials are wrong. Log out with docker logout and log back in, ideally using an access token.

Slow or failing uploads are often caused by very large images. Use smaller base images like alpine or slim variants, add a .dockerignore file, and use multi-stage builds to reduce image size.

Best Practices for Pushing Docker Images

Use meaningful version tags (such as semantic versioning like 1.2.0) instead of relying only on latest, since latest makes it hard to know which version is actually running. Never bake secrets, API keys, or passwords into your images, especially if the repository is public. Scan images for vulnerabilities with docker scout before pushing. And automate the process with CI/CD tools like GitHub Actions so every release is built and pushed consistently.

Quick Reference: All Commands

bash

docker login
docker build -t my-app .
docker tag my-app yourusername/my-app:1.0
docker push yourusername/my-app:1.0

Conclusion

Pushing a Docker image to Docker Hub takes just four steps: log in, build, tag, and push. Once your image is on Docker Hub, you can pull it from anywhere, share it with your team, and plug it into your deployment workflows. Master this process and you’ve taken a key step toward a smooth container-based development pipeline.