rust-lang/docker-rust: the source behind the official Rust container images

This repository builds images, it does not contain Rust

The first thing to understand is that docker-rust is a build repository. It does not contain the Rust compiler, the standard library or any Rust source code. What it contains is the recipe for a container image that has those things in it, plus the machinery that turns the recipe into the published artifacts. The full list of top-level entries is short enough to read in one breath:

Everything in that list is infrastructure. The three Dockerfile templates are variants, the two directories hold the generated Dockerfiles for the stable and nightly channels, `versions.toml` is the manifest of what gets published, and `x.py` is the script that performs the generation. The repository is written mostly in Dockerfile and a Python script, which is why the project lists its primary language as Dockerfile rather than Rust. Anyone arriving here expecting Rust code will not find it, and anyone who wants the image itself should pull it rather than clone this.

Three templates means three different trade-offs on one image

The presence of `Dockerfile-alpine.template`, `Dockerfile-debian.template` and `Dockerfile-slim.template` is the core design decision, and it is one of distribution rather than of Rust. Alpine is built on the musl C library rather than glibc, which gives a much smaller image but changes the rules for native dependencies, since a crate linking against a system library has to find a musl-compatible build of it. The Debian template trades size for compatibility, giving a base with the glibc and the package ecosystem most Rust projects expect when they need something like OpenSSL or libpq. The slim template sits in between. Which one a given tag uses is not something the README in this repository documents, and that is the first place the reader is pointed to the Docker Hub page instead. For a team choosing a tag, that distinction decides whether a native dependency will link, and it is worth checking before pinning rather than after a build fails at link time.

versions.toml is the contract between the repo and the published tags

The `versions.toml` file at the root is where the mapping from Rust releases to container tags is recorded. It sits alongside the two channel directories, `stable/` and `nightly/`, which hold the generated Dockerfiles for each release line. The division matters. The stable channel follows Rust releases, so the image tags move when the language moves, and a container that pins a stable tag will change its contents when the tag is repointed unless you pin a digest. The nightly channel is the one that tracks the moving target. The README gives the reference for it directly:

[`rustlang/rust:nightly`](https://hub.docker.com/r/rustlang/rust/).

An image tracking the Rust nightly toolchain is a different proposition from the stable images, because the toolchain underneath it changes without a version bump, and a build that worked yesterday can fail today for reasons that have nothing to do with your code. That is the argument for using it only in a controlled CI environment where a failure is visible and reproducible, not as the base image of a service whose behaviour has to be stable.

x.py is where the templates become images

The generation step is driven by `x.py`, a Python script that takes the templates and the version manifest and produces the concrete Dockerfiles and image metadata. This is the pattern the whole Docker official images ecosystem uses, and it is the reason a change to this repository does not immediately change what you pull. The script expands the template per variant, substitutes the Rust version and the base image details for that tag, and writes out the results into the channel directories. The value of the approach is that a single edit covers every platform and every tag at once, so a fix to the install step or the user setup does not have to be repeated per release. The cost is that the template syntax is not Docker's own, so reading a template tells you roughly what the image does but not exactly what the resulting file contains.

The README here is generated, and the real documentation is on Docker Hub

The README in this repository is a stub, and it says so in a comment rather than leaving you to guess. It is generated over in docker-library/docs, specifically in the docker-library/docs/rust directory, and the note at the top of the file records that it comes from a generate-repo-stub-readme.sh script in that repository. The full readme, with the usage instructions and the information about contributing and issues, is on the Docker Hub page for the image. That split has a practical consequence for anyone writing documentation about Rust containers: the instructions they need are not in the repository, they are on the registry site, and the two are updated on different schedules. The GitHub README covers what this repository is for, the nightly channel, and the licence, and leaves everything else to Docker Hub.

A merged change can take time to reach Docker Hub

The README addresses the most common confusion people hit with these repositories head on. If you see a change merged here that does not show up on Docker Hub yet, the answer is in another repository: the `library/rust` manifest file in the docker-library/official-images repository, and especially the pull requests carrying the `library/rust` label on that repository. The official images process is documented in the readme of docker-library/official-images. So there are at least three repositories involved in a change landing in a published image, and the publishing step is asynchronous with respect to the merge. If you are pinning a specific Rust version in a base image and want certainty about its contents, the manifest in official-images is the place to check rather than the release notes of this repository.

The licence is a choice between Apache-2.0 and MIT

The licence section gives the unusual combination of two permissive licences with an explicit choice for the user:

Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
[https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)> or the MIT license
<LICENSE-MIT or [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)>, at your
option. Files in the project may not be
copied, modified, or distributed except according to those terms.

Both texts are in the repository, as LICENSE-APACHE and LICENSE-MIT, and the wording puts the choice with the person using the files rather than with the project. Practically, that means you can take the build scripts under whichever of the two terms suits the project you are redistributing them into. Apache-2.0 carries an explicit patent grant and a notice requirement, while MIT is shorter and asks for little beyond attribution, and the difference between them rarely matters for a set of Dockerfiles but does matter for some corporate licence policies. The point of the dual arrangement is that this is build tooling that other organisations modify and redistribute, so the terms were chosen to be permissive enough not to obstruct that.

Where docker-rust is the wrong repository

Two limits are obvious. The first is that it is not the place to learn how to run Rust in a container. Everything a user wants to know about the image lives on Docker Hub, and the repository README itself points there for the full readme, for contributing and for issues. A team that has read this repository and still cannot tell which base variant a given tag uses has to go and read the Docker Hub page or the manifest file. The second is that this is build and publishing infrastructure, not a library you depend on. Depending on it means depending on tag semantics and on the publication pipeline, not on an API with a version you can pin. For a service that needs a fixed compiler and a fixed set of system libraries, the honest approach is to build your own base image from a pinned Rust release, or to pin a digest of a published tag, rather than to track this repository's output.

Editorial conclusion

docker-rust fits a team that needs to understand exactly how the rust image is built, pin a specific toolchain tag with confidence about what is inside it, or contribute a change to the image itself rather than to Rust. It is the wrong repository to look to for guidance on using containers, since the usage readme is generated elsewhere and hosted on Docker Hub. Before you pin a tag, check the `library/rust` manifest in the docker-library/official-images repository, since the README warns that a change merged here can take time to appear on Docker Hub.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. rust-lang/docker-rust on GitHub