# moby hands you two importable modules and a root module it tells you not to import

> Moby is the Go toolkit Docker builds its engine from, and it now separates what you may depend on from what you may only build. The root module is declared binaries only with no API stability guarantee, the old github.com/docker/docker module is frozen, engine tags carry a docker- prefix that must not be fetched with go get, and releases are supported on a best efforts basis with two named commercial alternatives.

**moby/moby** — The Moby Project - a collaborative project for the container ecosystem to assemble container-based systems.

- Repository: https://github.com/moby/moby
- Website: https://mobyproject.org/
- Stars: 72,148 · Forks: 19,239
- Language: Go
- License: Apache-2.0
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/moby-moby

## The root module produces binaries and is explicitly not a library

The go.mod at the root of the repository declares `module github.com/moby/moby/v2`, and the project is direct about what that module is for. It produces binaries only, it is not intended to be imported as a Go library, and it has no API stability guarantees.

The importable surface is two other modules. `github.com/moby/moby/client` is the Go client for the Docker Engine API, and `github.com/moby/moby/api` holds the API types shared between client and server. Those two are described as the supported public Go modules.

The consequence is that the obvious move is the wrong one. If you are looking for a Moby package to import, the root path is not it, and the guarantee you would want is the one it explicitly withholds. Because there is no stability promise, a change to anything you did manage to import from the root can arrive in any release with no deprecation period and no migration note aimed at importers, because the project does not consider itself to have importers. Read the root module as buildable source for an engine, and take your dependencies from client and api where the project has committed to a public surface.

## github.com/docker/docker is frozen, and the import change is the easy half

The project marks this with an important notice. Starting with Docker v29, released November 2025, the Go module `github.com/docker/docker` is deprecated and will not be updated.

The mechanical part of moving is two import lines:

```diff
- 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"
```

The project is direct that this is not the hard part. It notes that v29 includes many breaking API changes, naming option structs, renamed methods and moved types, and points at the v29.0.0 release notes for the full list of Go SDK changes.

So the consequence is a migration you cannot stage indefinitely. The compiler will find the renamed methods and the moved types, but option structs change how you pass configuration, which is a review of every call site rather than a find and replace. And you cannot fall back to the old module to buy time, because it is frozen rather than merely discouraged. Plan the work against the v29.0.0 release notes, and treat the import path change as the last step of the job rather than the first.

## docker- prefixed tags must not be fetched with go get

Moby cuts two unrelated sets of version tags, and the project is explicit that they are not interchangeable.

Docker Engine releases are tagged with a `docker-` prefix, for example `docker-v29.0.0` for Docker Engine 29.0.0. Those tags exist only to build the Docker Engine binary from the root module, and the instruction is that they must not be consumed via `go get`. The client and api modules carry their own tags and are versioned independently, given as `client/v1.x.x` and `api/v1.x.x`.

The three most recent releases show both lines running at once: docker-v29.8.1 on 2026-09-15, docker-v29.8.0 on 2026-09-03, and client/v0.6.0 on 2026-09-03.

The consequence is that no number on one line means anything on the other. Engine 29.8.1 tells you nothing about which client release you want, and the client is still pre-1.0 at v0.6.0, so it carries no compatibility promise of its own. Note also that the documented example tag shape, client/v1.x.x, is not the shape currently being cut. If you pin these, correlate them by reading release notes rather than by comparing version numbers, and never point go get at a docker- tag.

## Support is best efforts, and the page names the two products that are not

Two paragraphs on the project page settle the support question before you ask it. The releases are supported by the maintainers, community and users on a best efforts basis only. And for customers who want enterprise or commercial support, Docker Desktop and Mirantis Container Runtime are named as the appropriate products for those use cases.

The audience section says the same thing from the other side: Moby is intended for engineers, integrators and enthusiasts looking to modify, hack, fix, experiment, invent and build systems based on containers, and it is not for people looking for a commercially supported system.

There is a related boundary worth noting. The project states that it is not intended as a location for support or feature requests for Docker products, being a place for contributors to work on open source code and fix bugs. So a question about Docker behaviour that you file here may simply be redirected to the Docker product, even though Docker is committed to using Moby as its upstream.

The consequence is a procurement one. If your requirement includes someone answering when something breaks, this repository is the wrong place to look and says so twice. Budget for Docker Desktop or Mirantis Container Runtime, or accept that you are running an engine on community coverage and plan your own escalation path. A separate obligation sits in the Legal section, which notes that use and transfer of Moby may be subject to restrictions by the United States and other governments, and that ensuring your use does not violate applicable law is your responsibility.

## The Makefile is an environment variable passthrough, so the build config is not in the repository

The Makefile starts small. DOCKER defaults to docker, BUILDX to `$(DOCKER) buildx`, and DOCKER_GITCOMMIT is captured from `git rev-parse HEAD` and exported. After that it is a long list of environment variables forwarded into the build, including BUILDFLAGS, KEEPBUNDLE, DOCKER_BUILD_ARGS, DOCKER_BUILDKIT, DOCKER_GRAPHDRIVER, DOCKER_LDFLAGS, DOCKER_PORT, DOCKER_REMAP_ROOT, DOCKER_ROOTLESS, DOCKER_STORAGE_OPTS, DOCKER_USERLANDPROXY, DOCKER_EXPERIMENTAL and DOCKER_FIREWALL_BACKEND, followed by the test controls TEST_SKIP_INTEGRATION, TEST_SKIP_INTEGRATION_CLI, TEST_INTEGRATION_FAIL_FAST, TESTCOVERAGE and FLAKY_EXTRA_TESTS.

One comment shows how far this goes. DOCKER_LDFLAGS passes parameters to the `-ldflags` option of `go build`, with the example of changing the built-in graphdriver priority list at build time:

```
make DOCKER_LDFLAGS="-X github.com/moby/moby/v2/daemon/graphdriver.priority=overlay2,zfs" dynbinary
```

The consequence is that the effective build configuration lives in your shell or in your CI, not in the checkout. Two engineers building the same commit with different variables can produce different binaries, which is a reproducibility problem you solve by recording the variables rather than by reading the Makefile. And the presence of FLAKY_EXTRA_TESTS tells you the maintainers know which tests are intermittent, so a green run with that variable set is not the same claim as a green run without it.

## The dev container pins two Docker CLI versions four majors apart

The Dockerfile at the root of the repository installs two different versions of the Docker CLI, and the difference is deliberate enough to be commented.

The first is the current one, `DOCKERCLI_VERSION=v29.8.1`, pulled from the docker/cli repository, with a renovate datasource comment above it. The second is `DOCKERCLI_INTEGRATION_VERSION=v25.0.5`, and the comment above that one says it is the cli version used for integration-cli tests.

So the dev container you develop in and the CLI that the integration-cli suite exercises are not the same client. The repository has two test suites to match, `integration/` and `integration-cli/`, and the older CLI line is what keeps the legacy path honest.

The consequence is about what a green run proves. A passing integration-cli run tells you the v25-era CLI still behaves, and tells you nothing about v29, which is the version everything else in the container uses. If you are changing CLI-facing behaviour, establish which suite covers the code you touched before you trust a pass, or you will get a green build that never exercised your change. The same file pins other moving parts for you: buildx at 0.37.1, compose at v5.5.1, and a registry image at 3.1.2 for the integration tests, so the test environment is a moving target you have to keep in step.

## The dependency set carries release candidates and commit-pinned forks

Reading go.mod tells you what kind of project this is. The module is `github.com/moby/moby/v2` on go 1.26.6, with a tool directive for the protobuf generators. The dependency list spans AWS SDK v2 for CloudWatch logging and instance metadata, Azure packages including hcsshim, Cloudflare cfssl, coreos go-systemd, a long set of containerd modules covering cgroups, logs, plugins, NRI and ttrpc, and the distribution reference library.

Several entries are not clean releases, and the comments say why. hcsshim is pinned at v0.15.0-rc.4 and containerd/platforms at v1.0.0-rc.5, both release candidates. Graylog2/go-gelf is pinned to a pseudo-version commented as the head of the v2 branch. Microsoft/go-winio is pinned to a commit with a comment pointing at an hcsshim pull request. docker/distribution is marked v2.8.3+incomp, the standard Go marker for an incompatible major version.

The consequence is scoped by who you are. For a user, none of this changes how you run a container. For anyone building outside the project's own tooling, it means you are outside the configuration its maintainers test, and the vendor/ directory at the root is what makes a build reproducible. One detail worth noting: go.mod declares go 1.26.6 while the Dockerfile pins GO_VERSION to 1.26.8, so the declared minimum toolchain and the image the project builds in are different versions.

## Batteries included but swappable puts the integration work on you

The principles section sets out four commitments: modular, with components that have well-defined functions and APIs that work together; batteries included but swappable, meaning there are enough components to build a fully featured container system but most can be replaced by different implementations; usable security, described as secure defaults without compromising usability; and developer focused, with the note that the APIs are intended as components aimed at developers and that documentation and UX is aimed at developers rather than end users.

The layout matches. extpoints/ holds the extension point machinery that makes swapping possible, api/, client/ and daemon/ are the layers, errdefs/ centralises errors, and cmd/, contrib/, pkg/, internal/, man/, docs/, hack/, releases/ and project/ sit around them. There are three Dockerfiles, one plain, one simple and one for Windows.

The consequence follows from the word swappable. A design that invites you to replace most components puts the work of knowing which seams exist and which contracts hold across a swap on your side of the seam, and the project does not pretend otherwise by aiming its documentation at developers. If you want a container runtime you install and use, this is the wrong shape of project. If you want components to assemble into a system you control, that is exactly the shape, and the four principles are a fair description of what you are signing up for.

## Conclusion

Depend on Moby through github.com/moby/moby/client and github.com/moby/moby/api, and treat github.com/moby/moby/v2 as source you build rather than a package you import, because the project states the root module is not intended as a library and carries no API stability guarantee. Three things to settle before you start. Whether you are still on github.com/docker/docker, which is deprecated as of Docker v29, released November 2025, and will not be updated, so the migration cannot wait. How you correlate a client version with an engine version, since the two are versioned independently and the client line is still pre-1.0 at v0.6.0 against engine v29.8.1. And where your support comes from, because releases are covered on a best efforts basis only and the project names Docker Desktop and Mirantis Container Runtime for anyone who needs a contract. If your requirement includes export control, read the Legal section and the NOTICE document before you transfer anything.

## FAQ

### Why is the container project called Moby?

The project page does not explain the name. What it does document is the relationship: the components and tools in the Moby Project are initially the open source components that Docker and the community built for the Docker Project, Docker is committed to using Moby as the upstream for the Docker Product, and other projects are encouraged to use it as an upstream too. So the name is inherited from that lineage rather than defined anywhere on the page.

### What is Moby's most famous song?

That question is not about this project. The repository here is a Go toolkit for the container ecosystem, created by Docker to assemble container based systems, and it contains no music. If you are after a container engine, the importable Go modules are github.com/moby/moby/client and github.com/moby/moby/api, and the most recent releases listed are docker-v29.8.1 and client/v0.6.0.

### Who is Moby Moby?

Moby is not a person here, it is a collaborative open source project created by Docker to enable and accelerate software containerization, described as a Lego set of toolkit components. It is aimed at engineers, integrators and enthusiasts who want to modify, hack, fix, experiment and build systems based on containers, and it is explicitly not for people looking for a commercially supported system.

### What does the word moby mean in English?

The project page gives no definition of the word and uses it only as a project name. The one place the page turns to the word as a legal subject is the Legal section, which states that use and transfer of Moby may be subject to certain restrictions by the United States and other governments, that it is your responsibility to ensure your use or transfer does not violate applicable laws, and that further information is at bis.doc.gov.

## Sources

- [Official documentation](https://mobyproject.org/)
- [Official README](https://github.com/moby/moby#readme)
- [Project repository](https://github.com/moby/moby)
- [Release notes](https://github.com/moby/moby/releases)

---

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