docker tag: Name & Re-tag Images for Push

Give an image the registry-qualified name it needs to be pushed.

docker tag creates an additional name (a reference) pointing at an existing image. It does not copy data. This page covers tagging for push and common naming mistakes.

What it does

docker tag SOURCE TARGET adds a new tag/reference to an image. Both names point at the same image ID. You tag before push so the name encodes the destination registry and repository.

Common usage

Terminal

docker tag myapp:latest ghcr.io/owner/myapp:1.2.3
docker tag myapp:latest ghcr.io/owner/myapp:latest
docker tag abc123def ghcr.io/owner/myapp:sha-abc123

Common errors in CI

"Error parsing reference: ... is not a valid repository/tag" usually means an uppercase letter in the repository path (registry repositories must be lowercase) or an invalid character. "No such image" means the SOURCE name or ID does not exist locally - build or pull it first. Tag names allow letters, digits, underscores, periods, and dashes, up to 128 characters.

Related guides

docker push: Usage, Options & Auth Errors in CIHow docker push works: uploading a tagged image to a registry, naming requirements, and the denied/unauthoriz… docker build: Usage, Options & Common CI ErrorsHow docker build works: building an image from a Dockerfile, tagging, build args, target stages, and the buil… docker images: List Images, Filters & FormattingHow docker images works: listing local images, filtering dangling layers, custom formatting, and using it to… docker login: Authenticate to a Registry in CIHow docker login works: authenticating to Docker Hub, GHCR, or ECR with a token from stdin, and the auth erro…