Image Naming and Tagging Conventions
What you'll learn: How to properly name and tag container images for clear versioning, organization, and retrieval across registries.
The Anatomy of an Image Name
Container images follow a hierarchical naming structure that tells the runtime where to find the image and which version to use. A fully-qualified image name has three parts:
[registry-hostname]/[repository-name]:[tag]
- Registry hostname: Where the image lives (e.g.,
docker.io,gcr.io,mycompany.azurecr.io) - Repository name: The path and name identifying the image (e.g.,
nginx,myorg/myapp) - Tag: A version label (e.g.,
v1.2.3,latest,staging-20240115)
Why This Matters
Without a registry hostname, the container runtime assumes a default (usually Docker Hub). Without a tag, it defaults to latest — which can cause unpredictable behavior since "latest" is just a convention, not necessarily the newest version.
Tagging Best Practices
- Use semantic versioning for releases:
myapp:1.0.0,myapp:1.0.1 - Include environment indicators:
myapp:prod-v2.1,myapp:dev - Add commit SHAs for traceability:
myapp:a3f8d92 - Avoid relying on
latestin production — it's ambiguous and can change unexpectedly
Think of image tags like file versions in a shared drive: report-latest.docx doesn't tell you when it was created or what's inside, but report-2024-Q1-final.docx does.
Key Takeaway: Proper image naming combines registry location, repository path, and meaningful tags to create reproducible, traceable deployments across environments.