Pushing Images to Docker Hub and Private Registries
Step-by-step tutorial on tagging and pushing container images to Docker Hub, Harbor, AWS ECR, and self-hosted OCI registries.
Published on • November 18, 2026
AI Assistant

Building a container image locally is only the first step in software delivery. To make your application available to remote servers, Kubernetes clusters, or team members, you must publish (push) your built images to a central OCI container registry.
In this step-by-step tutorial, we will walk through tagging conventions, authenticating with registries, pushing images to Docker Hub and self-hosted private registries (like Harbor or AWS ECR), and troubleshooting common push errors.
The Image Push Workflow
+-----------------------+ 1. docker build -t app:v1 +-----------------------+
| Local Docker Daemon | --------------------------------> | Local Image Store |
+-----------------------+ +-----------------------+
| |
| 2. docker tag app:v1 registry.com/team/app:v1 |
v v
+-----------------------------------------------------------------------------------+
| 3. docker push registry.com/team/app:v1 |
| - Uploads missing layer blobs in parallel |
| - Uploads manifest JSON |
+-----------------------------------------------------------------------------------+
|
v
+-----------------------------------------------------------------------------------+
| Remote Container Registry (Docker Hub / Harbor / ECR / Self-Hosted) |
+-----------------------------------------------------------------------------------+
Step 1: Correct Image Tagging
The docker push command uses the image repository name to determine where to push the image. If your tag does not include a domain host prefix, Docker assumes the destination is Docker Hub (docker.io).
Tagging Syntax
docker tag <local-image>:<local-tag> <target-registry-domain>/<namespace>/<repository>:<tag>
Examples:
- Docker Hub (User Account):
docker tag my-web-app:latest johnsmith/web-app:v1.0.0 - Docker Hub (Organization):
docker tag my-web-app:latest acme-corp/web-app:v1.0.0 - Self-Hosted Registry (Port 5000):
docker tag my-web-app:latest registry.internal.net:5000/finance/web-app:v1.0.0 - AWS Elastic Container Registry (ECR):
docker tag my-web-app:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/finance/web-app:v1.0.0
Step 2: Authenticating with the Registry
Before pushing, you must establish an authenticated session using docker login.
Option A: Logging into Docker Hub
# Enter your Docker Hub username and Personal Access Token (PAT)
docker login
Option B: Logging into a Self-Hosted Private Registry
docker login registry.internal.net:5000 -u myuser -p mytoken
Option C: Logging into AWS ECR (via AWS CLI)
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com
Step 3: Executing docker push
Once tagged and authenticated, push your image:
docker push registry.internal.net:5000/finance/web-app:v1.0.0
Sample Output:
The push refers to repository [registry.internal.net:5000/finance/web-app]
a29b4e710d22: Pushed
f83b1928a410: Layer already exists
c71982b54e11: Pushed
v1.0.0: digest: sha256:7f8a91b2c3d4e5f6... size: 1572
Notice Layer already exists: Docker reuses layers already present in the remote registry, significantly saving bandwidth and upload time!
Pushing All Tags at Once
If you have assigned multiple tags to the same image (e.g., :v1.0.0, :v1.0, and :latest), you can push all tags associated with a repository name using --all-tags (or -a):
docker push --all-tags registry.internal.net:5000/finance/web-app
Troubleshooting Common Push Errors
1. denied: requested access to the resource is denied
- Cause: You are not logged in, or your account lacks write/push permissions for the target repository.
- Fix: Re-run
docker loginwith a token that haspushpermissions.
2. http: server gave HTTP response to HTTPS client
- Cause: You are attempting to push over unencrypted HTTP to a private registry, but Docker CLI requires TLS by default.
- Fix: Configure TLS/HTTPS on your registry, or add the registry to your host’s
insecure-registrieslist in/etc/docker/daemon.json(development only).
3. name unknown: repository name not found
- Cause: The repository namespace has not been created yet on registries that require pre-creation (like ECR or Harbor).
- Fix: Create the target project/repository in the registry console before pushing.
Summary Checklist
- Always tag your image with the explicit target registry domain and namespace.
- Authenticate securely using Personal Access Tokens or temporary cloud credentials (
docker login). - Leverage layer re-use by keeping base layers consistent across services.
- Verify the push completed by checking the returned SHA-256 digest.