moby/moby: the upstream engine behind Docker, and how to build against it

What moby/moby actually is, and who the README says it is for

Moby is not a container runtime you install and run as a product. The README describes it as a Lego set of toolkit components, the framework for assembling them into custom container-based systems, and a place to experiment. Components named in the README include container build tools, a container registry, orchestration tools and a runtime.

The audience statement is unusually blunt for a project of this size. Moby is intended for engineers, integrators and enthusiasts looking to modify, hack, fix, experiment, invent and build systems based on containers. The README then adds what it is not: not for people looking for a commercially supported system. For commercial support it names Docker Desktop and Mirantis Container Runtime.

The relationship with Docker is the part most readers get wrong. The components in Moby are initially the open source components Docker and the community built for the Docker project, and Docker is committed to using Moby as the upstream for the Docker Product. Other projects are encouraged to use Moby as an upstream too. So Docker Engine is downstream of this repository, not a separate product that happens to share code.

One consequence is stated directly: Moby is not the place for support or feature requests for Docker products. Releases are supported by maintainers, community and users on a best efforts basis only. If your interest in this repository is a bug you hit in a Docker Desktop install, you are in the wrong tracker.

The Go module split, and why github.com/docker/docker is deprecated

The most consequential recent change for anyone writing Go against this codebase is the module split. Starting with Docker v29, released November 2025, the Go module github.com/docker/docker is deprecated and will not be updated. That is a hard cutoff, not a soft preference.

The supported public modules are narrower than the old single import path. github.com/moby/moby/client is the Go client for the Docker Engine API. github.com/moby/moby/api holds API types shared between client and server. The root module github.com/moby/moby/v2 is the codebase for building container engines such as Docker Engine, and the README is explicit that it produces binaries only, is not intended to be imported as a Go library, and has no API stability guarantees.

That last sentence matters more than the deprecation notice. A project that publishes a client and an api module with independent versioning, while telling you the root module is off limits as a dependency, is drawing a boundary between integration surface and engine internals. Treating the root module as a library is a decision you make against the documentation.

The migration itself is a mechanical import swap, but the README warns that v29 includes many breaking API changes: option structs, renamed methods, moved types. The full list lives in the v29.0.0 release notes, and the README does not reproduce it. Budget for reading those notes rather than trusting a find-and-replace.

Installing the client module and making a first call

There is no install step for Moby as a whole; you either build the engine from the root module or import the client and api modules. The README gives the import path migration as a diff, which is the clearest statement of the new paths.

- import "github.com/docker/docker/client"
+ import "github.com/moby/moby/client"

- import "github.com/docker/docker/api/types"
+ import "github.com/moby/moby/api/types"

If you are starting fresh rather than migrating, add the client module to your own module and let the Go toolchain resolve it. The README does not print a go get line for these modules, so the command below follows from the module paths it lists rather than from a quoted example.

go get github.com/moby/moby/client
go get github.com/moby/moby/api

What you should see is both modules added to your go.mod with their own version tags, which are independent of the engine's. The README states the client and api modules are versioned independently with their own tags, in the form client/v1.x.x and api/v1.x.x.

Do not reach for the engine tag when pinning the client. Docker Engine releases are tagged with a docker- prefix, for example docker-v29.0.0 for Docker Engine 29.0.0, and the README says those tags are only used to build the Docker Engine binary from the root module and must not be consumed via go get. A go.mod that pins a docker- prefixed tag is a mistake the documentation anticipates and rules out.

Building the engine from source, and the Makefile knobs you inherit

Building the engine is a separate exercise from consuming the client. The repository carries a Dockerfile, Dockerfile.simple, Dockerfile.windows and a docker-bake.hcl, and the Makefile is the entry point for builds and tests. The Makefile defines DOCKER and BUILDX variables and derives DOCKER_GITCOMMIT from git rev-parse HEAD, so a build is stamped with the commit it came from.

The Makefile passes a long list of environment variables through to Docker's build scripts, which is effectively the supported configuration surface for a custom build. Some are self-explanatory (DOCKER_DEBUG, DOCKER_EXPERIMENTAL, DOCKER_ROOTLESS, DOCKER_GRAPHDRIVER). Others are less obvious. DOCKER_LDFLAGS is documented in a Makefile comment as a way to pass additional parameters to go build's -ldflags option, and the comment gives a concrete example: changing a built-in graphdriver priority list at build time with -X github.com/moby/moby/v2/daemon/graphdriver.priority=overlay2,zfs, applied to the dynbinary target.

That example is worth pausing on. It means the graphdriver priority order is not purely a runtime configuration concern in this codebase; it can be baked into the binary. If you are assembling a custom engine and expected to tune storage drivers after deployment, the Makefile suggests a different workflow.

The Dockerfile pins its own toolchain: GO_VERSION defaults to 1.26.8, BASE_DEBIAN_DISTRO to bookworm, and the dev container installs a CLI at DOCKERCLI_VERSION=v29.8.0, buildx at 0.37.0 and compose at v5.5.1. There is also a separate DOCKERCLI_INTEGRATION_VERSION=v25.0.5 used for integration-cli tests, which is a notably older CLI than the one installed for development. The Dockerfile does not explain that divergence, and it is the kind of detail that will confuse anyone reading the file expecting a single CLI version.

Where moby/moby is the wrong tool

The clearest wrong-tool case is stated by the project itself. If you need commercial or enterprise support, the README redirects you to Docker Desktop or Mirantis Container Runtime. Moby releases are supported on a best efforts basis by maintainers, community and users. That is a support model, not a service level, and choosing Moby for a production platform means accepting it.

The second wrong-tool case is subtler and catches Go developers. Importing github.com/moby/moby/v2 as a library is explicitly outside the intended use. The README states the root module produces binaries only and has no API stability guarantees. A team that vendors the root module to reuse an internal package has no compatibility promise to lean on across releases, and v29 already carried many breaking API changes to the modules that are meant to be imported.

The third is the tracker. Moby is not a location for support or feature requests for Docker products. Filing there does not route your request to Docker's product process.

A fourth limitation is architectural rather than policy. The README's principles call Moby modular and without too strong an opinion on user experience, with documentation and UX aimed at developers rather than end users. Components can be swapped for different implementations. That flexibility is real, but it means the project will not make ergonomic choices on your behalf. If you want a system that has already made those choices, you are looking at the wrong layer.

Alternatives, and the difference that matters

The honest comparison is not Moby against another container engine. It is Moby against the two things people reach for when they actually want to run containers: Docker Engine as a product, and containerd directly.

Docker Engine is the downstream product built from this repository. The README states Docker is committed to using Moby as the upstream for the Docker Product. Choosing Docker Engine over Moby means choosing a supported binary with a release process aimed at users, over a codebase aimed at people who want to modify and assemble. The API is the same lineage, so the client module is relevant either way.

containerd is the more interesting comparison because it sits inside Moby's own dependency graph rather than beside it. The go.mod lists github.com/containerd/containerd/v2 v2.3.5, along with containerd/cgroups/v3, containerd/continuity, containerd/nri and containerd/platforms. Moby is not a thin wrapper over containerd; it is an engine that composes containerd with a much wider set of components, including its own build tooling, registry code and orchestration pieces. Reaching for containerd directly means giving up that assembly layer and taking on the integration work yourself. Reaching for Moby means accepting the assembly layer's opinions about which components belong together, even as the README insists most of them can be swapped.

The practical difference in approach: containerd gives you a runtime and a plugin model, while Moby gives you a framework plus a set of components and a stated willingness to have them replaced. If you do not intend to replace anything, the framework is overhead.

Licence, maintenance and the cost of tracking upstream

Moby is licensed under the Apache License, Version 2.0, with the full text in the LICENSE file. That is a permissive licence, but the repository also carries a NOTICE document and a legal section stating that use and transfer of Moby may be subject to restrictions by the United States and other governments, and that it is your responsibility to ensure your use or transfer does not violate applicable laws. That is an export-control statement, not a licensing restriction, and it is unusual enough in a container project to be worth reading before you ship. Nothing here is legal advice; read the LICENSE and NOTICE and take your own counsel.

Maintenance is easy to state from the repository itself. The project is not archived, and the last push was on 2026-08-28. Recent releases include docker-v29.8.0-rc.1 on 2026-08-28, docker-v29.7.2 on 2026-08-06 and docker-v29.7.1 on 2026-07-31. A release candidate at the head of that list is normal for an engine project and means the newest tag is not the one to build against.

The upgrade cost is concentrated in the module split. If you are on github.com/docker/docker, the deprecation means the path will not receive updates, and the README directs you to the v29.0.0 release notes for the full list of Go SDK changes. Because the client and api modules are versioned independently, you can move them on their own schedule rather than tracking engine releases. What you cannot do is treat the root module as a stable dependency and expect that to hold. The repository also carries a ROADMAP.md, SECURITY.md and CONTRIBUTING.md, so the process for reporting a security issue and for proposing changes is documented in-tree rather than assumed.

Editorial conclusion

Adopt moby/moby if you are building or modifying a container engine, or if you need the Go client and API types under github.com/moby/moby/client and github.com/moby/moby/api. Do not adopt it if you want a commercially supported runtime or a place to file Docker product feature requests; the README points those users at Docker Desktop and Mirantis Container Runtime. Before writing code, verify which module you actually need: the root module github.com/moby/moby/v2 produces binaries only and carries no API stability guarantees, while the docker- prefixed release tags must not be consumed via go get.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes