Pushing Docker images to a private repository is essential when working in a secure environment or hosting proprietary code.
This guide will walk you through the step-by-step process of pushing an image to a private Docker registry.
1️⃣ Prerequisites
Before you start, make sure you have:
- Docker installed on your system (
docker --version) - Access to a private repository (e.g., Docker Hub private repo, AWS ECR, Azure Container Registry, Google Artifact Registry, Harbor, etc.)
- Login credentials (username/password, token, or IAM role)
2️⃣ Step-by-Step Process
Step 1 — Login to the Private Registry
Use the docker login command:
docker login <registry_url>
Examples:
- Docker Hub:
docker login docker.io - AWS ECR:
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account_id>.dkr.ecr.<region>.amazonaws.com
If successful, you’ll see:
Login Succeeded
Step 2 — Tag Your Local Image
You must tag the image with your private registry path.
Syntax:
docker tag <local_image>:<tag> <registry_url>/<namespace>/<image_name>:<tag>
Example for Docker Hub:
docker tag myapp:latest docker.io/myusername/myapp:latest
Example for AWS ECR:
docker tag myapp:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest
Step 3 — Push the Image
docker push <registry_url>/<namespace>/<image_name>:<tag>
Example:
docker push docker.io/myusername/myapp:latest
You’ll see output showing each image layer being uploaded.
3️⃣ Verifying the Push
- Docker Hub: Check your repository online.
- AWS ECR / Azure / GCP: Use the respective CLI or web console to verify.
- Self-hosted registry: Pull the image from another machine to confirm:
docker pull <registry_url>/<namespace>/<image_name>:<tag>
4️⃣ Common Issues & Fixes
| Problem | Cause | Solution |
|---|---|---|
unauthorized: authentication required | Wrong credentials | Run docker login again |
denied: requested access to the resource is denied | Wrong namespace or no permission | Check repository name and permissions |
| Slow push | Large image size | Use .dockerignore to exclude unnecessary files and multi-stage builds to reduce size |
📌 Summary
Pushing an image to a private Docker registry involves:
- Logging in to the registry
- Tagging your image with the registry path
- Pushing the image with
docker push