3.2.1 Image Repository Names
A focused guide to Image Repository Names, connecting core concepts with practical Docker and container operations.
Image repository names identify a distinct line of related images — typically all the versions of one particular application — within a registry, distinguishing them from the specific tags that identify individual versions within that repository.
Repository as a Grouping of Versions
A repository name groups together every tagged version of a particular image; myapp as a repository might have tags 1.0, 1.1, 2.0, and latest, all referring to different images that are nonetheless considered versions of "the same" application.
docker images myapp
This lists every locally available tag belonging to the myapp repository, showing them as related versions of the same underlying application.
Namespaced Repository Names
Repository names are often namespaced with an organization or team name, which avoids naming collisions between similarly named images from different sources within the same registry.
docker pull library/nginx
docker pull bitnami/nginx
Both of these are repositories named nginx, but namespaced differently (library and bitnami), referring to entirely different images maintained by different sources.
Choosing Repository Names Within an Organization
Within a private registry, repository naming conventions typically reflect organizational structure — a team or project name as the namespace, followed by the specific application's name as the repository itself.
docker push registry.example.com/payments-team/billing-service:1.0
Repository Names and Discoverability
A clear, consistent repository naming scheme makes images easier to discover and understand at a glance — seeing registry.example.com/payments-team/billing-service immediately conveys both ownership and purpose, which a more arbitrary name would not.
docker search billing-service
Why Repository Naming Matters
Thoughtful repository naming is largely an organizational and discoverability concern rather than a technical one, but it has real practical impact: a registry with thousands of images is far easier to navigate and reason about when repository names consistently reflect ownership and purpose.