# docker-library/ruby is a template and a version matrix, not a Dockerfile

> The docker-library/ruby repository is the Git source of the Docker Official Image for ruby, a set of per-version directories generated from a shared template by shell scripts, with the human readable documentation living on Docker Hub instead. It is worth reading to understand how the official Ruby images are produced, and it is not where you look for Ruby documentation.

**docker-library/ruby** — Docker Official Image packaging for Ruby

- Repository: https://github.com/docker-library/ruby
- Website: http://www.ruby-lang.org/
- Stars: 625 · Forks: 322
- Language: Shell
- License: BSD-2-Clause
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/docker-library-ruby

## What this repository is, and what it is confused with

The repository description is the Docker Official Image packaging for Ruby, and the README states plainly that this is the Git repo of the Docker Official Image for ruby. It also includes a warning that the project should not be confused with any official ruby image provided by ruby upstream.

That distinction is the first thing to understand, because two different artifacts are easy to mix up. This repository is the packaging work done under the Docker Official Images programme, maintained by the Docker Community according to the README. The full readme on how to use this Docker image, along with information regarding contributing and issues, is on the Docker Hub page rather than here.

So the division of labour is deliberate. Usage documentation lives with the image on Docker Hub, and the Git repository holds the build inputs. Anyone who lands here looking for how to run a Ruby container in production is in the wrong place, and the README says so by pointing at the Docker Hub page for the full readme.

The homepage field points at ruby-lang.org, which is a reminder of what this project is and is not. It packages a language runtime for containers; it is not the language itself, and nothing here changes how Ruby behaves.

## The README in this repository is generated

There is a comment at the bottom of the README that says the file is generated by generate-repo-stub-readme.sh from the docker-library/docs repository. The reason for that is stated just above it: the full image description on Docker Hub is generated and maintained in the docker-library/docs repository, specifically in the ruby directory.

This is worth pausing on, because it explains the odd shape of the repository. There is no hand-written usage guide here to read, and no local history of why the documentation says what it says. The text you see in the README is a stub pointing at the canonical copy, and the canonical copy is edited in a different repository.

The same pattern appears in how issues and pull requests are handled. For outstanding ruby image pull requests, the README directs you to the pull requests with the library/ruby label on the official-images repository, and it names the library/ruby file in that repository as the current source of truth for ruby. Changes to the image are therefore tracked in one place, and the packaging repository is where the build inputs are merged.

There is also a pointer for a specific confusion: the section headed with a question about seeing a change merged here that does not show up on Docker Hub yet. The answer is the FAQ entry in the docker-library/faq repository, on an image's source changing in Git. Merging here and appearing on Docker Hub are separate events with a lifecycle in between, and the README acknowledges that gap rather than hiding it.

## Version directories and the template that fills them

The top level of the repository is where the design shows. There are four version directories, 3.3, 3.4, 4.0 and 4.1-rc, plus a Dockerfile.template and the shell scripts that work with it.

A template plus a version matrix is the shape of the problem. Ruby ships minor versions on a schedule and the ecosystem moves with it, so an image cannot be a single static Dockerfile. The per-version directories hold the variant files for each supported line, and the template holds what is common. The 4.1-rc directory shows the third pattern, a release candidate that gets its own entry before it is a stable line.

The scripts around them are named for the job. apply-templates.sh is the script that turns the template into the per-version directories. versions.sh sits next to versions.json, which is the manifest of versions, and update.sh is the entry point for pulling new versions in. generate-stackbrew-library.sh produces the Homebrew library metadata, which is how the same packaging feeds package managers outside Docker.

The repository is written mostly in Shell, with the scripts doing the assembly and the JSON file holding the data. The README does not describe how these pieces interact in detail, and it does not need to, because the audience for this repository is the maintainers of the image rather than the users of it.

## The Ruby image also carries a Rust toolchain

Two files in the root do not obviously belong to a Ruby packaging repository: rust.json and rust.sh.

Their names indicate that the image is packaged with a Rust toolchain in mind as well as the Ruby runtime, and the file naming matches the pattern of the other data file, versions.json. Since a Ruby image that also installs Rust is unusual enough to be worth noticing, this is a good example of what the repository layout tells you that the README does not.

The practical reason is not documented in this repository. If you need to know exactly which Rust version an image ships, or whether the toolchain is present in every variant or only some, the answer is not in the files listed here. The place to look would be the generated image description on Docker Hub and the library/ruby file in the official-images repository, which the README names as the source of truth.

That is a general lesson about this repository. It holds the inputs, and it holds them in a shape that is easy to diff. The answers to questions about what a given image contains live further downstream, in the built artefact and in the metadata published alongside it.

## The official image against a Dockerfile you write yourself

The real alternative to pulling the official Ruby image is writing your own Dockerfile with the Ruby runtime as the base, or using one of the other ruby images published on Docker Hub.

The difference in approach is about who decides what is in the image and when it changes. The official image is produced by a template and a version matrix, with the versions manifest as the single list of what exists. That structure exists because the image is maintained by a community under a shared programme rather than by one team for one application. Reproducibility across many users, and a shared process for base image updates, come at the cost of a manifest-driven, generated layout that you cannot simply edit by hand.

A hand-written Dockerfile makes the opposite trade. You choose the base image, the system packages and the Ruby version, and nothing changes under you unless you change it. The cost is that you now own patching, and you own the differences between your environment and everyone else's.

The upstream ruby image mentioned in the README is a third case, a separate official image provided by the Ruby project itself. The README only warns against confusing the two, and it does not describe how they differ in content, so choosing between them on the basis of this repository alone is not possible. What the warning does establish is that when you see a ruby image reference, there is more than one thing it could be, and the reference itself is the thing to check.

## Licence, no releases, and a repository that keeps moving

The licence is BSD-2-Clause, with a LICENSE file at the root. For an image that most people consume as a prebuilt artefact, that matters less than it would for a library, but it does mean the packaging code itself can be reused and modified under a short permissive licence with a retained notice.

The repository has no GitHub releases. That is expected for this kind of project, since the artefact that gets a version is the image on Docker Hub rather than a source archive, and the version list lives in versions.json and in the library/ruby file of the official-images repository.

The maintenance signal to note is the push history rather than the tags. The last push was on 2026-10-14 and the repository is not archived, so the packaging work is still moving. The primary language of the repository is Shell, which fits: the interesting logic in an official image repository is the script that assembles variants from a template, not the runtime it packages.

For a team pinning a Ruby version in CI, the practical consequence is that the set of supported versions changes over time, and the directory listing here is the fastest way to see which lines are currently packaged. When a version disappears from the listing, that is the signal to move your pin.

## Conclusion

docker-library/ruby suits an engineer who wants to know exactly how the official Ruby image is assembled, which versions are supported and when a base image changes, and the generated template makes that answer concrete. It is the wrong place to look for Ruby language documentation, for a custom image with your own system packages, or for a pinned version that has already moved out of the version directories. Verify first which Ruby versions the repository currently carries, since the directory listing is the only catalogue here, and check the library/ruby file in the docker-library/official-images repository, which the README names as the source of truth for what actually ships to Docker Hub.

## FAQ

### Where is the documentation for the Docker Official Image for ruby?

The full readme on how to use the image, plus contributing and issue information, is on the Docker Hub page for ruby. The description here is a generated stub pointing at the ruby directory in the docker-library/docs repository.

### What is the difference between docker-library/ruby and the official ruby image from Ruby upstream?

The README states that this repository is the Git repo of the Docker Official Image for ruby and warns that it should not be confused with any official ruby image provided by ruby upstream. It does not describe how the two images differ in content.

### Which Ruby versions does the docker-library/ruby repository package?

The repository currently holds per-version directories for 3.3, 3.4, 4.0 and 4.1-rc, with versions.json as the manifest. The README names the library/ruby file in the docker-library/official-images repository as the source of truth for what ships to Docker Hub.

### Why did a change merged into the repository not appear on Docker Hub?

Merging the source and publishing the image are separate steps with a lifecycle in between. The README points at the FAQ entry in the docker-library/faq repository, An image's source changed in Git, now what?, for the full official images change lifecycle.

## Sources

- [docker-library/ruby on GitHub](https://github.com/docker-library/ruby)
- [Issues](https://github.com/docker-library/ruby/issues)
- [License: BSD-2-Clause](https://github.com/docker-library/ruby/blob/master/LICENSE)
- [Project website](http://www.ruby-lang.org/)
- [README](https://github.com/docker-library/ruby/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/docker-library-ruby