Push a Tagged Docker Image to a Registry

Push the wrong tag with docker image push and it is live for everyone who can pull, so do it once and do it deliberately. This guide gets one local image onto Docker Hub or a private registry, checks the digest the registry returns, and stops you publishing every stale local tag by accident. Allow about fifteen minutes plus upload time. The installed command is Docker 29.8.1 from docker-ce-cli version 5:29.8.1-1~ubuntu.24.04~noble.

• You need: a working Docker daemon, an image already present locally, a registry repository where you have push permission, and credentials for that registry.
• About sudo: the ordinary commands below do not need it when your account can already access the daemon. Adding sudo only to the push can leave you on a different Docker configuration with a different set of credentials.

1. Check the command and find the local image

Start with read-only checks. Replace LOCAL_IMAGE with the image you intend to publish:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker image ls --filter reference='LOCAL_IMAGE'
REPOSITORY   TAG       IMAGE ID       CREATED       SIZE

The filter output must contain the source image and tag you expect. If it is empty, build or load the image first. Do not use an image name from memory: a similarly named local image can be a different build.

2. Create the registry tag

The tag selects the push target, not a separate registry option. The reference has this shape:

[REGISTRY_HOST[:PORT]/]NAMESPACE/REPOSITORY:TAG

For Docker Hub, use your account or organisation namespace. For a private registry, include its hostname and port when required. Tagging creates another local reference to the same image; it does not upload anything:

$ docker image tag LOCAL_IMAGE:SOURCE_TAG registry.example.com:5000/team/example-app:2026-09-23
$ docker image ls --filter reference='registry.example.com:5000/team/example-app:2026-09-23'

Expect one row for the new reference, with an image ID that matches the source row. Image names use lower-case letters, digits, hyphens, underscores and full stops in the relevant components. Keep the repository and tag simple enough to review in a deployment log.

$ docker image inspect registry.example.com:5000/team/example-app:2026-09-23 --format '{{.RepoTags}}'

3. Authenticate without leaving a password in shell history

Registry credentials are managed by docker login. Run it for the same registry host used in the image tag:

$ docker login registry.example.com:5000
Username: YOUR_REGISTRY_USER
Password: [hidden]

Prefer the registry's supported token or credential-helper flow. A successful login normally ends with a message confirming that authentication succeeded. If the registry uses a different login endpoint, follow that registry's instructions and keep the hostname in the image tag consistent.

Authentication is security-sensitive but does not change the image. If the login wrote credentials to a client configuration you do not want to keep, use the Docker credential-management procedure for that environment to remove them after the push.

4. Push one tag

$ docker image push registry.example.com:5000/team/example-app:2026-09-23
The push refers to repository [registry.example.com:5000/team/example-app]
...
2026-09-23: digest: sha256:EXAMPLE_DIGEST size: EXAMPLE_SIZE

Layer progress is verbose by default, and existing layers may be reported as already present. The digest line is the registry's content address for the pushed manifest. Save it with the release record if you need a stable value to deploy later, rather than relying only on the mutable tag.

Verify the local reference still exists:

$ docker image ls --filter reference='registry.example.com:5000/team/example-app:2026-09-23'

To verify the remote object, use the registry's inspection or pull-by-digest mechanism from a machine that has access to it. The push prints the digest, but a successful local command is not proof that a different account can pull the image.

5. Push every tag in one repository

Use --all-tags only when you have deliberately reviewed every local tag under the target repository:

$ docker image ls --format '{{.Repository}}:{{.Tag}}' \
    | grep '^registry.example.com:5000/team/example-app:'
$ docker image push --all-tags registry.example.com:5000/team/example-app

The command pushes all tags of that local repository, not merely the tag you last looked at. That suits a coordinated batch, but it can publish stale or experimental tags.

6. Handle multi-platform images carefully

The installed command also accepts --platform os/arch[/variant], for example:

$ docker image push --platform linux/amd64 registry.example.com:5000/team/example-app:2026-09-23

This pushes a platform-specific manifest as a single-platform image. Docker's help and manual warn that the image index is not pushed, so other platform manifests and attestations are not preserved.

7. Stop or recover a failed push

Pressing Ctrl-C terminates the push. It does not delete layers or tags the registry has already accepted. A later push of the same tag may resume by reusing layers, so check the remote repository and the digest before retrying.

Common failures have different fixes:

• Name or tag error. The local target was not created as expected. Re-run docker image ls and docker image inspect; do not retag a different image just to make the command pass.
• unauthorized or denied. Usually the login, namespace or repository permission is wrong. Log in to the exact registry host and confirm the account has push access.
• Connection or timeout failure. It can leave a partial upload. Check registry health and network access, then retry the same reviewed reference.
• Tag must come off the registry. Use the registry's documented deletion and retention procedure. A local docker image rm removes only a local tag or image reference; it is not an undo for a remote push.