Create a Local Docker Image Tag Without Copying the Image

A deploy that runs the wrong version usually traces back to a stale docker tag, not a broken build. By the end of this guide, you will have added a second local name to an existing image, checked that both names point to the same image ID, and removed the extra tag again if it was only a test. Docker tag changes local image metadata. It does not build an image, copy its layers, or upload anything to a registry.

Allow about five minutes. You need the Docker CLI and access to a Docker daemon, plus an image already present locally. This guide was checked with Docker Community docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble, reporting Docker 29.8.1.

1. Check the command and source image

The command has exactly two positional arguments:

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

The source must already exist in the local image store. A tag is optional on each side. If you omit a source tag, Docker uses latest. That default is easy to miss: docker tag alpine example.invalid/alpine:review means alpine:latest, not the newest image available on a remote registry.

List local images before changing anything. This needs no elevated privileges when your account can use Docker.

docker image ls --format '{{.Repository}}:{{.Tag}}\t{{.ID}}'
docker image inspect alpine:latest --format '{{.Id}}'

Expected output is a table row for the source and an image ID beginning with sha256:. If the inspect command says that the image is missing, obtain the image through your normal trusted workflow first, for example with docker pull alpine:latest. Pulling is a separate network and supply-chain decision, so do not treat a failed tag as permission to fetch an arbitrary image.

Checkpoint: the source is local

Continue only when docker image inspect alpine:latest succeeds, or replace that example with an image name you have deliberately selected. Neither docker tag nor docker image tag will create a missing source image.

2. Add a descriptive target tag

Use a target name that records the role or destination you intend. A registry-looking name does not publish anything by itself. The following creates a local tag for the installed Alpine image:

docker tag alpine:latest example.invalid/alpine:review

There is normally no output when the operation succeeds. The target may include a registry hostname, namespace and tag, but Docker still changes only the local image store. The command is an alias for docker image tag, so these two forms have the same effect:

docker image tag alpine:latest example.invalid/alpine:review

Do not use a target name as evidence that an image was pushed. Uploading requires a separate docker push, credentials and a reachable registry.

3. Verify that the tag points to the same image

Compare the IDs rather than relying on the names. A tag is a reference, so the source and target should report the same ID immediately after the operation.

docker image inspect alpine:latest example.invalid/alpine:review \
  --format '{{.RepoTags}} {{.Id}}'

Expected output contains both names and the same sha256: value on each line. You can also list only the two references:

docker image ls --no-trunc \
  --format '{{.Repository}}:{{.Tag}} {{.ID}}' \
  | grep -E '^(alpine:latest|example[.]invalid/alpine:review) '

If the IDs differ, stop and inspect the exact source and target strings. Common distractions include checking latest when the intended tag was a version, or comparing a shortened ID from one command with a digest from another. Tagging itself does not change the image contents.

4. Remove a temporary tag

Removing a tag is a state-changing operation. Check the target name first, and do not remove a tag that another deployment, script or compose file uses.

docker image inspect example.invalid/alpine:review --format '{{.RepoTags}}'
docker image rm example.invalid/alpine:review

Docker should report that the tag was untagged. This removes the reference, not necessarily the image layers. If another tag still refers to the image, the image remains available under that name. To restore the reference, run the original tag command again:

docker tag alpine:latest example.invalid/alpine:review

docker image rm can remove more than a tag when no references remain, so read its output before confirming any prompt. Never use a broad image-pruning command as an undo for one test tag.

5. Diagnose the usual failures

"requires 2 arguments" means the source or target was omitted, or shell quoting collapsed the command. Use the full two-name form from the synopsis.

"No such image" means the source reference is not present locally. Check spelling, repository, tag and the Docker context. docker context show tells you which daemon the CLI is addressing; a different context can have a different image store.

Permission denied is an access problem, not a reason to add sudo automatically. First check whether your account is meant to access Docker. Docker daemon access is highly privileged because it can control containers and mounted host paths. Follow your system's approved Docker access policy before changing group membership or using elevated privileges.

The target already exists usually means you are moving that tag to the source image you named. Verify the current target ID before replacing a name used by automation. If the target is a release or deployment label, coordinate the change and record the previous reference so it can be restored.

Done means