3.2.1.1 Local Image Names
A focused guide to Local Image Names, connecting core concepts with practical Docker and container operations.
Local image names are the repository and tag combinations assigned to an image on a specific Docker host, which may or may not match the name the same image will eventually have once pushed to a registry — naming locally and naming for distribution are related but distinct steps.
Naming an Image at Build Time
When building an image, a local name and tag can be assigned directly, without yet referencing any registry at all, since the image only needs to exist locally for local use, such as testing.
docker build -t myapp:dev .
This image exists only on the local host under this name until explicitly pushed somewhere else.
Renaming or Retagging for a Registry
Before an image can be pushed to a particular registry, it generally needs to be tagged with that registry's address as part of its name, which can be done without rebuilding the image at all.
docker tag myapp:dev registry.example.com/myteam/myapp:1.0
docker push registry.example.com/myteam/myapp:1.0
The docker tag command here does not create new image content; it simply assigns an additional name to the same already-built image, which is why this step is instantaneous regardless of the image's size.
Multiple Local Names for the Same Image
A single image, identified by one underlying digest, can have several local names simultaneously, each potentially useful for a different purpose — a development tag, a registry-qualified tag, and a "latest" alias, all pointing at the same content.
docker tag myapp:dev myapp:latest
docker images --filter "reference=myapp"
This lists every local name currently pointing at images in the myapp repository, which may include several tags referring to the exact same underlying image.
Why Distinguishing Local From Registry Names Matters
Understanding that local naming and registry naming are separate, lightweight operations clarifies why retagging an image for a different registry or repository is fast and does not require rebuilding — only the metadata pointing to the already-existing image content changes, not the content itself.