DEV Community

Vincent Tommi
Vincent Tommi

Posted on

Push Your First Docker Image to Docker Hub: A Beginner’s Guide

#programming #documentation #docker #beginners

New to Docker and want to share your Django app with the world? If you’ve built a Docker image for your Django project using Docker Compose, this guide will show you how to push it to Docker Hub, step by step. We’ll use a simple example based on a Django app and explain everything in a way that’s easy for beginners to follow. Let’s dive in!

What Are Docker and Docker Compose?
Docker is a tool that packages your app (like a Django website) into a “container” so it runs the same way on any computer. Think of it as a portable lunchbox for your app. Docker Compose is a tool that helps you build and manage these containers using a file called docker-compose.yml.

In this guide, we’ll use a docker-compose.ymlfile that builds a Django app image named django-hello-world:0.0.1. Our goal is to share this image on Docker Hub, a website where you can store and share Docker images

Prerequisites

  1. Docker and Docker Compose: Install them on your computer (get them here).

  2. Docker Hub Account: Sign up for free at hub.docker.com.

  3. A docker-compose.yml file like this one:

services:
  django:
    image: django-hello-world:0.0.1
    build: .
    ports:
      - "8000:8000"
Enter fullscreen mode Exit fullscreen mode

This file tells Docker Compose to build an image named django-hello-world:0.0.1 for your Django app.

Step 1: Check Your Built Image
First, build your image by running this command in the same folder as your docker-compose.yml:

docker compose build
Enter fullscreen mode Exit fullscreen mode

This creates an image for your Django app. To see it, type:

docker images
Enter fullscreen mode Exit fullscreen mode

docker images

REPOSITORY           TAG       IMAGE ID       CREATED       SIZE
django-hello-world   0.0.1     ab4d5df8b752   1 hour ago    1.11GB
Enter fullscreen mode Exit fullscreen mode

The REPOSITORY and TAG show your image’s name (django-hello-world) and version (0.0.1). If you don’t see this, make sure docker compose build worked. The image name might include your project folder’s name (e.g., my_django_app_django:0.0.1) if you didn’t specify the imagefield, but our example uses django-hello-world:0.0.1.

Step 2: Sign In to Docker Hub
Before sharing your image, log in to Docker Hub. In your terminal, type:

docker login
Enter fullscreen mode Exit fullscreen mode

output

docker login
Authenticating with existing credentials... [Username: vincenttomi]

i Info → To login with a different account, run 'docker logout' followed by 'docker login'


Login Succeeded
Enter fullscreen mode Exit fullscreen mode

Step 3: Tag Your Image for Docker Hub
Docker Hub needs your image to have a name that includes your username, like vincenttomi/django-hello-world:0.0.1. Right now, your image is named django-hello-world:0.0.1. Let’s add your username with a “tag.”

Run this command, replacing vincenttomi with your Docker Hub username:

docker tag django-hello-world:0.0.1 vincenttomi/django-hello-world:0.0.1
Enter fullscreen mode Exit fullscreen mode

This gives your image a new name. To check it worked, run:

docker images
Enter fullscreen mode Exit fullscreen mode

You should see:

REPOSITORY                    TAG       IMAGE ID       CREATED       SIZE
django-hello-world            0.0.1     ab4d5df8b752   1 hour ago    1.11GB
vincenttomi/django-hello-world 0.0.1     ab4d5df8b752   1 hour ago    1.11GB
Enter fullscreen mode Exit fullscreen mode

You can also use the latest tag (common for the newest version):

docker tag django-hello-world:0.0.1 vincenttomi/django-hello-world:latest
Enter fullscreen mode Exit fullscreen mode

Step 4: Push Your Image to Docker Hub
Now, send your image to Docker Hub with:

docker push vincenttomi/django-hello-world:0.0.1
Enter fullscreen mode Exit fullscreen mode

This uploads your image. It might take a minute or two. When it’s done, visit hub.docker.com/u/yourusername in your browser to see your image!

If you tagged it as latest, use:

docker push vincenttomi/django-hello-world:latest
Enter fullscreen mode Exit fullscreen mode

Common Mistake: “Image Does Not Exist” Error

If you see an error like:

An image does not exist locally with the tag: vincenttomi/django-hello-world
Enter fullscreen mode Exit fullscreen mode

It means Docker can’t find the image you’re trying to push. This happens if you didn’t tag the image (Step 3) or used the wrong tag (e.g., latest instead of 0.0.1).

Fix: Check your image names with docker images. Make sure vincenttomi/django-hello-world:0.0.1 (or latest) is listed. If not, retag your image with the docker tag command (Step 3), then try docker push again.

Bonus: Simplify with Docker Compose
To make pushing easier, update your docker-compose.yml to include your Docker Hub username:

services:
  django:
    image: vincenttomi/django-hello-world:0.0.1
    build: .
    ports:
      - "8000:8000"
Enter fullscreen mode Exit fullscreen mode

After building with docker compose build, push with:

docker compose push
Enter fullscreen mode Exit fullscreen mode

This pushes your image without needing to tag it manually.

Conclusion
Congratulations on pushing your first Docker image to Docker Hub! You’ve taken your Django app from your computer to the cloud, making it easy to share or use anywhere. By building, tagging, and pushing your image, you’ve learned key Docker skills. Keep exploring—try pulling your image on another machine with docker pull vincenttomi/django-hello-world:0.0.1 or build another Docker project. You’re well on your way to mastering Docker!

Top comments (0)