docker-library/official-images: the source of truth behind Docker Hub's library namespace

What the official-images repository actually contains

People searching for Docker official images usually land on Docker Hub, not on this repository. The confusion is understandable, because the name suggests a collection of Dockerfiles. It is not that. According to the README, the Docker Official Images are curated images hosted on Docker Hub, and this repository is where the library definition files that describe them live. The top-level listing shows the shape of it: a library/ directory, a bashbrew-oriented Dockerfile, and a set of naughty-*.sh scripts that act as lint gates. The README also points out that Hub descriptions for these images are stored separately in the docker-library/docs repository, so even the marketing copy for a tag is not here. The audience is narrow and specific: maintainers of upstream projects who want an image accepted into the program, and engineers who need to trace a tag back to a definition. If you are looking for a Dockerfile to copy, you are in the wrong repository.

How a tag becomes a multi-architecture image

The mechanism is declarative. A library definition file names a repository, lists tags and aliases, and gives an instruction format that bashbrew consumes. The README separates these concerns into sections on filenames, tags and aliases, and instruction format, which tells you the file is a manifest rather than a build script. From there the pipeline resolves each tag to source repositories and builds per architecture. The README states that non-amd64 architectures are included under the non-prefixed images via OCI image indexes, so a plain docker run hello-world resolves to the right platform without a tag suffix. That is the part worth internalizing: the architecture-specific Hub namespaces such as arm64v8 and s390x are not separate products, they are views onto the same index. For a full account of how a changed source becomes a rebuilt image, the README defers to the docker-library/faq repository and to meta-scripts for the build process source files. This repository is the input, not the factory.

Installing the toolchain and reading a library file

There is no install step for the images themselves; you pull them with Docker. What you can build locally is the review environment. The repository Dockerfile starts from oisupport/bashbrew:base and installs ca-certificates, wget, git, gawk, bzip2 and jq, then copies a pinned crane binary from gcr.io/go-containerregistry/crane. It sets two environment variables that matter:

ENV DIR /usr/src/official-images
ENV BASHBREW_LIBRARY $DIR/library

BASHBREW_LIBRARY is how bashbrew finds the definition files, so any command you run against this checkout depends on that variable pointing at the library/ directory. The image also copies crane into /usr/local/bin/ for use by diff-pr.sh. To get a working checkout, clone the repository and build that Dockerfile; the comment in the Dockerfile notes the base image is itself built via .github/workflows/.bashbrew/action.yml from the docker-library/bashbrew repository. Once inside, the useful first move is to open a file under library/ and read how a tag maps to a git ref and a Dockerfile path. The README's instruction format section is the key to that syntax. The repository does not document a single convenience command that prints a resolved tag, so expect to read the definition files directly.

Where the review process will slow you down

The Review Guidelines are the real gate, and they are explicitly subjective in places. The README says the standard is hard to define due to subjectivity, then splits the review into maintainership, repeatability, consistency, clarity, init, cacheability, security, and multiple architectures. Each of those is a place a pull request can stall. Security alone is subdivided into image build, runtime configuration, and security releases. The maintainership rule is the one most likely to surprise a contributor: if you do not represent upstream and upstream later becomes interested, the README expects steps toward a smooth transition of image maintainership to upstream. In other words, you can do the work and still be asked to hand it over. There is also a hard separation between this repository and docker-library/docs, so acceptance here does not finish the job; the README tells contributors to be prepared to submit a PR there as well, pending acceptance of the image here. Budget for two review cycles, not one.

The lint scripts and what they catch

The top-level listing includes naughty-commits.sh, naughty-constraints.sh, naughty-from.sh, and naughty-sharedtags.sh, plus _bashbrew-cat-sorted.sh, diff-pr.sh, pr-urls.sh, and toc.sh. The naming is blunt on purpose: these are checks that fail a contribution rather than advise on it. naughty-from.sh implies a constraint on which base images a definition may reference. naughty-sharedtags.sh implies a rule about tags that collide across repositories. naughty-constraints.sh suggests validation of the constraint fields in definition files. diff-pr.sh needs gawk, bzip2, jq and crane, all of which the Dockerfile installs, which tells you it compares the effect of a pull request on built images rather than just the text diff. The README does not document what each script rejects or how to run them individually, so read the scripts before opening a pull request. Treating them as a pre-flight check is cheaper than discovering a violation during review.

When this repository is the wrong tool

If your goal is to build a custom image, this repository adds nothing. The Dockerfile here produces a bashbrew environment, not your application. If you want a Dockerfile to adapt, the README points at Docker's own best-practices documentation and at the per-project source repositories, not at library/. And if you want an image for software that is not free or open source, the program's first tenet rules it out: the README lists focus on Free and Open-Source Software as the leading principle. A closed-source internal base image will not be accepted here no matter how well written it is. There is also a maintenance expectation that cuts against set-and-forget submissions. Version bumps and security fixes should be attended to in a timely manner, per the README, and the program actively rebuilds for updates and security fixes. If nobody on your team can commit to that cadence, an official image is the wrong home for your software.

Alternatives and how they differ

The closest alternative in kind is building and publishing your own image on Docker Hub under your own namespace. The difference is the review layer. Nothing in that path enforces the Review Guidelines, the naughty-* scripts, or the maintainership transition rule, and nothing places your image under hub.docker.com/u/library. What you give up is the curation signal; what you gain is control over tag policy and release cadence. A second alternative is to consume a distribution's own published images rather than a library image, which shifts the trust question to that vendor's pipeline and away from the OCI image index arrangement described here. A third is to build from source in your own CI and skip registries entirely, which removes the supply-chain question but also removes the multi-architecture index that makes docker run hello-world work unchanged across platforms. None of these is strictly better. The library program trades autonomy for review, and the review is the product.

Maintenance, licensing, and what to verify

The repository is not archived, and the last push was on 2026-09-21, so it is being touched. That says nothing about the cadence of any individual image, which depends on its maintainer. The repository is licensed Apache-2.0, per its LICENSE file. That covers the contents of this repository, meaning the definition files and scripts; it does not relicense the software inside the images, each of which carries its own upstream licence. If you are auditing a base image for licence compatibility, the Apache-2.0 file here is not the answer you need. Check the upstream project's licence and the image's own metadata instead. There is a SECURITY.md at the top level for reporting issues, and the README points to Libera.Chat channel #docker-library and GitHub issues for questions. For anything about how a source change propagates to a rebuilt image, the README redirects to the docker-library/faq repository, which is where that explanation actually lives.

Editorial conclusion

Adopt this repository as a reference when you need to know what a library tag actually points at, or when you are proposing an image for the program. Do not clone it expecting to build images locally: the Dockerfile here only prepares a bashbrew environment, and the actual source Dockerfiles live in per-project repositories. Before submitting anything, read NEW-IMAGE-CHECKLIST.md and the Review Guidelines in README.md, and check whether your upstream project already maintains its image, because the maintainership section expects a transition to upstream if upstream becomes interested.

Frequently asked questions

Official sources

1. docker-library/official-images on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README