3.2.1.2 Image Registry Namespaces

Image registry namespaces are the organizational prefixes within a registry — typically a username or organization name — that group related repositories together and prevent naming collisions between images published by different, unrelated sources.

Namespaces Distinguish Otherwise Identical Repository Names

Without namespaces, two different organizations both wanting to publish an image named api would collide; namespaces resolve this by scoping the repository name under each organization's own identifier.

docker pull acmecorp/api:1.0
docker pull othercorp/api:1.0

Both of these are repositories named api, but they refer to entirely unrelated images, distinguished entirely by their namespace.

The Default Namespace on Docker Hub

Official images on Docker Hub — base images for common languages and tools — are published under a special library namespace, which is why they can be referenced without any namespace prefix at all.

docker pull nginx
docker pull library/nginx

Both retrieve the same image, since nginx without an explicit namespace implicitly resolves to library/nginx.

Namespaces in Private Registries

In a private registry, namespaces are typically used to scope images by team or project, which both prevents naming collisions and makes ownership clear from the image name itself.

docker push registry.example.com/platform-team/auth-service:1.0
docker push registry.example.com/billing-team/invoice-service:1.0

Permissions Often Follow Namespace Boundaries

Many registries tie access control to namespaces, meaning a team's namespace can be configured so that only members of that team can push new images into it, while still allowing broader read access for pulling.

docker login registry.example.com
docker push registry.example.com/platform-team/auth-service:1.0

Why Registry Namespaces Matter

Namespaces are what allow a single registry to host images from many different, mutually unaware teams or organizations without naming conflicts, while also providing a natural boundary for access control and a clear visual indicator of ownership in every image reference.