top of page
Search

Namespace and Repository: The Most Straightforward Portion of an Image Name

Introduction

This article is the second in a three-part series on container image names. Part 1 provides the background for the series and a discussion of the image registry.


As a refresher, here’s a diagram of an example fully-qualified image name (FQIN) with the parts labeled:



Throughout this series, we’re using the following image names as examples.


  • python:3

  • cgr.dev/chainguard/python

  • nvcr.io/nvidia/pytorch:25.03-py3

  • registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:ubuntu-x86_64-latest


In today’s article, we’ll learn about the namespace and repository. (Note, the repository is different from the registry, which we covered in part 1.) This is the most straightforward portion of the image name, so let’s get right into it!


The Namespace


The namespace is the prefix of the repository portion of the image name. Depending on the registry, this may be called a group, project, organization, user, or some other name. Essentially, it describes the entity that owns the repository and, therefore, who published the image. It's also typically the scope for defining access (i.e., defining who can push or pull images).


Typically, the namespace is the portion between the registry name and the first slash in the repository name, as shown in the diagram above. However, this can vary depending on the registry implementation. For example, on GitLab and GitHub registries, the namespace is the path of the project hosting the image, which can be several path elements.


It’s worth noting that I’m using the word namespace here to capture all of these different naming conventions with one term. Be aware, though, that the word namespace can have different meanings depending on the context. For example, Linux kernel namespaces are a key component of running containers and have nothing to do with the image name.


If a namespace is not specified, the default on Docker Hub and registries that mimic it is library. This default is registry-specific and not defined in any standard.


Not all registries implement this default, and some don’t require a namespace at all. For example, the Kubernetes pause container is located at registry.k8s.io/pause, with no namespace.


Examining our example image names:


  • For python:3, the namespace is library.

  • For cgr.dev/chainguard/python, the namespace (organization) is chainguard.

  • For nvcr.io/nvidia/pytorch:25.03-py3, the namespace is nvidia.

  • For registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:ubuntu-x86_64-latest, the namespace (project) is gitlab-org/gitlab-runner.


The Repository


The repository is the portion of the image name after the registry and before the tag (including the namespace). This is typically the part of the name that describes the software package that the image contains. In some documentation, this is called the image name, which likely stems from familiarity with traditional package managers, where this would be the package name.


Using the FQIN terminology, we might think of this as an unqualified image name. It may tell us what is in the image, but it does not by itself tell us where the image comes from or what version it is.


The word repository may be confusing at first glance. Doesn’t a repository imply a collection, not a specific package? Well, yes. A repository is a collection of artifacts that make up one or more container images. The Open Container Initiative (OCI) Distribution Specification defines the term repository as “a scope for API calls on a registry for a collection of content (including manifests, blobs, and tags).”


The tag or digest (which we will cover in the next article) describes which artifacts to pull from the repository. However, all of the artifacts within a repository are generally for the same software package.


There is no default repository. This is the only portion of the image name that is required. (Keep in mind, though, that there can be a default namespace, as we learned earlier, which is part of the repository.)


Examining our example image names:


  • For python:3, the repository is library/python.

  • For cgr.dev/chainguard/python, the repository is chainguard/python.

  • For nvcr.io/nvidia/pytorch:25.03-py3, the repository is nvidia/pytorch.

  • For registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:ubuntu-x86_64-latest, the repository is gitlab-org/gitlab-runner/gitlab-runner-helper.


Recommendations


Unlike the registry, the namespace and repository are fairly straightforward. However, I can provide you with two recommendations, based on my experience as a Platform Engineer.


First, always specify the full repository name, including the namespace, even when the namespace is the default. This ensures that the intent is clear. Also, since the default of library is specific to a particular registry, different applications or client libraries may not implement it.


Second, always consult the vendor documentation to determine the correct repository for the application you wish to use. If there is no vendor-provided image, do the necessary research to pick the right image for your use case and risk tolerance. The same software package name in different namespaces may be built differently and have different features and levels of support.


Example


Let’s consider Ubuntu as an example. Canonical publishes three sets of images:


  • Development releases, including interim and unstable versions, are published to Amazon ECR Public in the ubuntu namespace.

  • Long Term Support (LTS) releases are published to Amazon ECR Public in the lts namespace.

  • Expanded Security Maintenance (ESM) images are provided to paying customers, via a different distribution channel.


So, if you are concerned about stability, maintenance, and support, you could use the lts namespace. That way, you’d be assured that you are always getting an LTS image, which would ostensibly reduce the overall risk.


Conclusion


I hope you enjoyed this deep dive into a small but important topic: the container image namespace and repository. Let’s take a moment to reflect on what we covered.

We learned that the repository generally describes the software package that the image contains.


  • We learned that the repository contains a namespace prefix.

  • We learned that the namespace generally describes who owns and published the image.

  • We learned that there is a default namespace.

  • We learned a couple best practices for using and specifying repositories.


In my next article, we’ll wrap up this series about container image names, focusing on the tag and digest. I hope to see you there!


Jason Miller is a Senior Platform Engineer at Clarity Business Solutions. You can find him on LinkedIn.


The mention of any image name, registry, or vendor does not constitute a recommendation or endorsement. These are solely provided as examples for demonstration purposes.

 
 
 
bottom of page