Push a Tagged Docker Image to the Right Registry

You will finish with a repeatable way to push one local Docker image to Docker Hub or a private registry, check the digest returned by the registry, and avoid accidentally publishing every local tag. The installed command is Docker 29.8.1 from docker-ce-cli version 5:29.8.1-1~ubuntu.24.04~noble. Allow about fifteen minutes, plus the time needed for the image upload.

You need a working Docker daemon, an image already present locally, a registry repository where you have push permission, and credentials for that registry. The ordinary Docker commands below do not need sudo when your account can already access the daemon. Adding sudo only to the push command can leave you using a different Docker configuration and 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.

Checkpoint: record the exact source reference, including its tag. A reference without a tag resolves to latest, which is a mutable name rather than a release identifier.

2. Create the registry tag

A push target is selected by the tag, not by 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. Its image ID should match 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.

Checkpoint: inspect the exact target before authenticating or pushing:

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

3. Authenticate without putting 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. Do not put a password directly after --password, and do not paste a token into a command that will be saved in shell history. 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 retain, use the Docker credential-management procedure for that environment to remove them after the push.

4. Push one tag

Review the target one last time. This next command changes remote registry state and may make the image available to other users or automated deployments:

$ 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

The layer progress is verbose by default. 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 command itself 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. This is useful for a coordinated batch, but it can publish stale or experimental tags. A failed tag does not make a blind retry safe: inspect the output and decide whether to push that tag separately.

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. Use this option only when you intentionally want one platform. For a multi-platform release, push the image index through the workflow that created it and verify the resulting index with the registry tooling.

7. Stop or recover a failed push

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

Common failures have different fixes:

• A name or tag error means 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 means the login, namespace or repository permission is wrong. Log in to the exact registry host and confirm that the account has push access.
• A connection or timeout failure can leave a partial upload. Check registry health and network access, then retry the same reviewed reference.
• If the tag itself must be removed from 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.