Distribution Release Notes

Welcome to the v3.1.2 release of registry!

This is a stable release

This patch release includes security fixes, storage and pagination fixes, and dependency updates.

Please try out the release binaries and report any issues at https://github.com/distribution/distribution/issues.

Notable Changes

• Verify manifest and blob content against the requested digest in the registry client, protecting digest-pinned requests and pull-through caches (CVE-2026-85747 / GHSA-685w-q87j-wqw3).
• Update security-sensitive dependencies, including gRPC, OpenTelemetry, and golang.org/x/crypto (#4912, #4963, #4965, #4968). The OTLP gRPC log exporter now honors TLS certificates configured through environment variables.
• Fix S3 tag pagination and catalog listing when one name is a prefix of another (#4898, #4904), and return an empty tag array after the final pagination marker (#4931).
• Fix Azure blob type migration and a concurrent append-write race (#4871, #4888).
• Check the storage backend directly when writing blobs to avoid stale descriptor-cache entries (#4868).
• Reject malformed manifest digests and out-of-order final upload chunks correctly (#4945), accept unknown total sizes in Content-Range (#4892), and preserve upstream error codes (#4917).
• Stop the upload purger during registry shutdown (#4956).
• Validate S3 redirect endpoints at driver initialization (#4870). …

Welcome to the v3.1.1 release of registry!

This is a stable release

Please try out the release binaries and report any issues at https://github.com/distribution/distribution/issues.

Notable Changes

• Fixes CVE-2026-41888
• Bounds-check the file basename in PurgeUploads Walk callback
• Add S3 Express One Zone support to the S3 storage driver (#4858)
• Fix tag list endpoint in proxy mode (#4846)
• Clamp oversized n query parameter in proxy mode instead of returning 400 (#4856)

See the full changelog below for the full list of changes.

What's Changed

• internal/client/auth/challenge: cleanups and minor refactor by @thaJeztah in https://github.com/distribution/distribution/pull/4832
• build(deps): bump go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp from 0.18.0 to 0.19.0 in the go_modules group across 1 directory by @dependabot[bot] in https://github.com/distribution/distribution/pull/4843
• build(deps): bump go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp from 1.42.0 to 1.43.0 in the go_modules group across 1 directory by @dependabot[bot] in https://github.com/distribution/distribution/pull/4850
• build(deps): bump github/codeql-action from 4.34.1 to 4.35.1 by @dependabot[bot] in https://github.com/distribution/distribution/pull/4840
• chore(build): Bump go version to latest by @milosgajdos in https://github.com/distribution/distribution/pull/4851 …

Welcome to the v3.1.0 release of registry!

This is a stable release

Please try out the release binaries and report any issues at https://github.com/distribution/distribution/issues.

Notable Changes

• Fixes CVE-2026-35172
• Fixes CVE-2026-33540
• Adds support for tag pagination (#4360, #4353)
• Fixes default credentials in Azure storage provider (#4619)
• Drops support for go1.23 and go1.24 and updates to go1.25

See the full changelog below for the full list of changes.

What's Changed

• docs: Update to refer to new image tag v3 by @schanzel in https://github.com/distribution/distribution/pull/4373
• Fix default_credentials in azure storage provider by @switchboardOp in https://github.com/distribution/distribution/pull/4619
• chore: make function comment match function name by @closeobserve in https://github.com/distribution/distribution/pull/4622
• build(deps): bump golang.org/x/net from 0.37.0 to 0.38.0 in the go_modules group across 1 directory by @dependabot[bot] in https://github.com/distribution/distribution/pull/4625
• fix: implement JWK thumbprint for Ed25519 public keys by @zhangyoufu in https://github.com/distribution/distribution/pull/4626
• fix: Annotate code block from validation.indexes configuration docs by @anzoman in https://github.com/distribution/distribution/pull/4629 …

Welcome to the v3.0.0 release of registry!

This is the first v3 stable release since v2.8.3 which is a culmination of years of hard work of the container community and registry maintainers!

If you are upgrading from v2.x and have never used any of the release candidates, please familiarise yourselves with the v2.x deprecations properly.

Deprecations

• oss and swift storage drivers are no longer supported
• docker/libtrust has been replaced with go-jose/go-jose in https://github.com/distribution/distribution/pull/4096
• client is no longer supported as a standalone package in https://github.com/distribution/distribution/pull/4126
• the default configuration path has changed to /etc/distribution/config.yml
• ManifestBuilder interface in 3886
• manifest.Versioned has been deprecated in favor of oci.Versioned in 3887
• reference package has been moved to github.com/distribution/reference in https://github.com/distribution/distribution/pull/4063

Changes since the last release candidate

Changes

<details><summary>7 commits</summary> <p> …

Welcome to the v3.0.0-rc.4 release of registry!

This is the fourth stable release candidate!

See the changelog below for a full list of changes.

Notable changes

• Enable MD5 check on GCS driver by @milosgajdos in https://github.com/distribution/distribution/pull/4586
• Azure driver [retry] fix by @milosgajdos in https://github.com/distribution/distribution/pull/4576, thanks @vespian for reporting!

What's Changed

• registry/storage: add an option to silence GC output. by @r4f4 in https://github.com/distribution/distribution/pull/4560
• Fix broken signing algorithm configuration for token authentication by @evanebb in https://github.com/distribution/distribution/pull/4578
• build(deps): bump github.com/go-jose/go-jose/v4 from 4.0.2 to 4.0.5 in the go_modules group by @dependabot in https://github.com/distribution/distribution/pull/4582
• build(deps): bump ossf/scorecard-action from 2.4.0 to 2.4.1 by @dependabot in https://github.com/distribution/distribution/pull/4579
• build(deps): bump actions/upload-artifact from 4.6.0 to 4.6.1 by @dependabot in https://github.com/distribution/distribution/pull/4580
• Enable MD5 check on GCS driver by @milosgajdos in https://github.com/distribution/distribution/pull/4586
• Update osx-setup-guide.md and com.docker.registry.plist by @andy-cooper in https://github.com/distribution/distribution/pull/4592 …

Welcome to the v3.0.0-rc.3 release of registry!

This is the third stable release candidate!

See the changelog below for a full list of changes.

Notable changes

• Fixes CVE-2025-24976, thanks @evanebb for reporting!

What's Changed

• build(deps): bump actions/upload-artifact from 4.3.6 to 4.5.0 by @dependabot in https://github.com/distribution/distribution/pull/4538
• ci: update bake-action to v6 by @crazy-max in https://github.com/distribution/distribution/pull/4554
• build(deps): bump actions/upload-artifact from 4.5.0 to 4.6.0 by @dependabot in https://github.com/distribution/distribution/pull/4553
• (security): Bump golang.org/x/net module by @milosgajdos in https://github.com/distribution/distribution/pull/4542
• (security): fix registry Token authentication bug by @milosgajdos in https://github.com/distribution/distribution/commit/f4a500caf68169dccb0b54cb90523e68ee1ac2be
• ci: fix bake build by @crazy-max in https://github.com/distribution/distribution/pull/4555
• Bump Go version by @milosgajdos in https://github.com/distribution/distribution/pull/4566
• Prep for v3-rc.3 release by @milosgajdos in https://github.com/distribution/distribution/pull/4568

Full Changelog: https://github.com/distribution/distribution/compare/v3.0.0-rc.2...v3.0.0-rc.3

Welcome to the v3.0.0-rc.2 release of registry!

This is the second release candidate of registry!

See the changelog below for a full list of changes.

Notable changes

• Upgrade Go OpenTelemetry https://github.com/distribution/distribution/pull/4508
• Add support for mTLS auth https://github.com/distribution/distribution/pull/4537
• Update Go runtime and Alpine image https://github.com/distribution/distribution/pull/4532

What's Changed

• build(deps): bump codecov/codecov-action from 4 to 5 by @dependabot in https://github.com/distribution/distribution/pull/4508
• Upgrade go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp by @krynju in https://github.com/distribution/distribution/pull/4507
• docs: Explain how to configure a list through env variables by @barbu110 in https://github.com/distribution/distribution/pull/4522
• build(deps): bump golang.org/x/crypto from 0.28.0 to 0.31.0 by @dependabot in https://github.com/distribution/distribution/pull/4531
• update xx to v1.6.1 for compatibility with alpine 3.21 and file 5.46+ by @thaJeztah in https://github.com/distribution/distribution/pull/4527
• chore: Bump alpine image version by @milosgajdos in https://github.com/distribution/distribution/pull/4532
• Update squizzi maintainer email by @squizzi in https://github.com/distribution/distribution/pull/4530
• feat(configuration): support mtls auth mod by @vitshev in https://github.com/distribution/distribution/pull/4537 …

Welcome to the v3.0.0-rc.1 release of registry!

This is the the first release candidate of registry!

See the changelog below for full list of changes.

Deprecated

• ManifestBuilder interface 3886
• Versioned in favor of oci.Versioned 3887

Notable Changes

• Attempt HeadObject on Stat call first before failing over to List in S3 driver 4401
• Use a consistent multipart chunk size in S3 driver 4424
• Build artifacts and images for linux/riscv64 4444
• Fix token verification chain in auth 4415
• Support custom exec-based credential helper in proxy mode https://github.com/distribution/distribution/pull/4438

What's Changed

• vendor: github.com/opencontainers/image-spec v1.1.0 by @thaJeztah in https://github.com/distribution/distribution/pull/3889
• Descriptor: do not implement Describable interface by @thaJeztah in https://github.com/distribution/distribution/pull/3886
• S3 driver: Attempt HeadObject on Stat first, fail over to List by @milosgajdos in https://github.com/distribution/distribution/pull/4401 …

Welcome to the 3.0.0-beta.1 release of registry!

This is the last major pre-release of registry.

See the changelog below for full list of changes.

Deprecated

• the default configuration path has changed to /etc/distribution/config.yml

Notable Changes

• Support for sparse indexes enables selective mirroring of platform images
• Auth config now requires explicit declaration of token signing algorithms if using an unsupported signing algorithm
• Support for OpenTelemetry tracing has been added
• Redis cache now supports clustering and custom TLS config
• Caching proxy bug fixes and minor improvements
• Garbage collection fixes and improvements
• Documentation has received several updates

What's Changed

• update: set User-Agent header in GCS storage driver by @milosgajdos in https://github.com/distribution/distribution/pull/4203
• version: export getter functions by @corhere in https://github.com/distribution/distribution/pull/4204
• feat: add GH issue template by @milosgajdos in https://github.com/distribution/distribution/pull/4206
• fix: build status badge by @milosgajdos in https://github.com/distribution/distribution/pull/4207
• docs: remove legacy kramdown options from link by @SKalt in https://github.com/distribution/distribution/pull/4209
• update: readme cleanup and fxes by @milosgajdos in https://github.com/distribution/distribution/pull/4208 …

This is the first major release in years!

It's an accumulation of effort that's bringing major improvements in performance, security and general code quality!

See the abridged changelog below and the full release log here.

Deprecations

• Image Manifest v2 Schema v1
• oss and swift storage drivers
• docker/libtrust has been replaced with go-jose/go-jose
• reference package has been moved to a dedicated repository (see here)
• client is no longer supported as a standalone package

Notable Changes

• reference package has been moved to its own dedicated repository
• Go module has changed from docker/distribution to distribution/distribution/v3
• Major performance improvements across all supported storage drivers
• Major dependencies updates (see the full list below)
• Online documentation is available at https://distribution.github.io/distribution/

What's Changed

• default autoredirect to false by @davidswu in https://github.com/distribution/distribution/pull/2800
• Add docs for autoredirect config parameter by @caervs in https://github.com/distribution/distribution/pull/2801 …

What's Changed

• Pass BUILDTAGS argument to go build by @marcusirgens in https://github.com/distribution/distribution/pull/3926
• Enable Go build tags by @thaJeztah in https://github.com/distribution/distribution/pull/4009
• reference: replace deprecated function SplitHostname by @thaJeztah in https://github.com/distribution/distribution/pull/4032
• Dont parse errors as JSON unless Content-Type is set to JSON by @thaJeztah in https://github.com/distribution/distribution/pull/4054
• update to go 1.20.8 by @thaJeztah in https://github.com/distribution/distribution/pull/4056
• Set Content-Type header in registry client ReadFrom by @thaJeztah in https://github.com/distribution/distribution/pull/4053
• deprecate reference package, migrate to github.com/distribution/reference by @thaJeztah in https://github.com/distribution/distribution/pull/4063
• digestset: deprecate package in favor of go-digest/digestset by @thaJeztah in https://github.com/distribution/distribution/pull/4064
• Do not close HTTP request body in HTTP handler by @milosgajdos in https://github.com/distribution/distribution/pull/4068
• Add v2.8.3 release notes by @milosgajdos in https://github.com/distribution/distribution/pull/4088

New Contributors

• @marcusirgens made their first contribution in https://github.com/distribution/distribution/pull/3926

Full Changelog: https://github.com/distribution/distribution/compare/v2.8.2...v2.8.3

What's Changed

• Revert registry/client: set Accept: identity header when getting layers by @ndeloof in https://github.com/distribution/distribution/pull/3783
• Parse http forbidden as denied by @vvoland in https://github.com/distribution/distribution/pull/3914
• Fix CVE-2022-28391 by bumping alpine from 3.14 to 3.16 by @thaJeztah (#3650)
• Fix CVE-2023-2253 runaway allocation on /v2/_catalog by @josegomezr 521ea3d9
• Fix panic in inmemory driver by @wy65701436 in https://github.com/distribution/distribution/pull/3815
• bump up golang version (alternative) by @thaJeztah in https://github.com/distribution/distribution/pull/3903
• Dockerfile: update xx to v1.2.1 by @thaJeztah in https://github.com/distribution/distribution/pull/3907
• update to go1.19.9 by @thaJeztah in https://github.com/distribution/distribution/pull/3908
• Add code to handle pagination of parts. Fixes max layer size of 10GB bug by @DavidSpek in https://github.com/distribution/distribution/pull/3893
• Dockerfile: fix filenames of artifacts by @thaJeztah in https://github.com/distribution/distribution/pull/3911

Full Changelog: https://github.com/distribution/distribution/compare/v2.8.1...v2.8.2

What's Changed

• Fix CVE-2022-28391 by bumping alpine from 3.14 to 3.16 by @thaJeztah (#3650)
• Fix CVE-2023-2253 runaway allocation on /v2/_catalog by @josegomezr 521ea3d9
• Fix panic in inmemory driver by @wy65701436 in https://github.com/distribution/distribution/pull/3815
• bump up golang version (alternative) by @thaJeztah in https://github.com/distribution/distribution/pull/3903
• Dockerfile: update xx to v1.2.1 by @thaJeztah in https://github.com/distribution/distribution/pull/3907
• update to go1.19.9 by @thaJeztah in https://github.com/distribution/distribution/pull/3908
• Add code to handle pagination of parts. Fixes max layer size of 10GB bug by @DavidSpek in https://github.com/distribution/distribution/pull/3893
• Dockerfile: fix filenames of artifacts by @thaJeztah in https://github.com/distribution/distribution/pull/3911

Full Changelog: https://github.com/distribution/distribution/compare/v2.8.1...v2.8.2-beta.2

NOTE: This is a pre-release that does not contain any artifacts!

What's Changed

• Fix runaway allocation on /v2/_catalog by @josegomezr 521ea3d9
• Fix CVE-2022-28391 by bumping alpine from 3.14 to 3.16 by @thaJeztah in https://github.com/distribution/distribution/pull/3650
• Fix panic in inmemory driver by @wy65701436 in https://github.com/distribution/distribution/pull/3815
• bump up golang version (alternative) by @thaJeztah in https://github.com/distribution/distribution/pull/3903
• Dockerfile: update xx to v1.2.1 by @thaJeztah in https://github.com/distribution/distribution/pull/3907
• update to go1.19.9 by @thaJeztah in https://github.com/distribution/distribution/pull/3908
• Add code to handle pagination of parts. Fixes max layer size of 10GB bug by @DavidSpek in https://github.com/distribution/distribution/pull/3893

Full Changelog: https://github.com/distribution/distribution/compare/v2.8.1...v2.8.2-beta.1

Welcome to the v2.8.1 release of registry!

The 2.8.1 registry release fixes the Go module issues that have popped up in the v2.8.0

There have been no changes made in the released binaries other than the bump of the Go runtime.

See the changelog below for a full list of changes.

CI

• ci: use proper git ref for versioning #3595
• Go: make Go version explicit and pin it to the latest 1.16 release #3604

Contributors

• CrazyMax
• Milos Gajdos

Changes

<details><summary>6 commits</summary> <p>

• 96cc1fdb FIx typo
• e744906f Update 2.8.1. release notes
• Prepare for v2.8.1 release (#3596)
  • 6736d188 Prepare for v2.8.1 release
• [2.8 backport] ci: use proper git ref for versioning (#3595)
  • 80acbdf0 ci: use proper git ref for versioning

</p> </details>

Dependency Changes …

registry 2.8.0

Welcome to the v2.8.0 release of registry!

The 2.8.0 registry release has been a long time overdue. This is the first step towards the last 2.x release. No further active development will continue on 2.x branch. Security vulnerability patches to 2.x might be considered, but all active development will be focussed on v3 release due in 2022. This release includes a security vulnerability fix along with a few minor bug fixes and improvemnts in documentation and CI.

See changelog below for full list of changes.

Bugfixes

• Close the io.ReadCloser from storage driver #3370
• Remove empty Content-Type header #3297
• Make ipfilteredby not required in cloudfront storage middleware #3088

Features

• Add reference.ParseDockerRef utility function #3002

CI build

• First draft of actions based ci #3347
• Fix vndr and check #3001
• Improve code quality by adding linter checks #3385

Documentation

• Add redirect for old URL #3197 …

Welcome to the v2.8.0-beta.1 release of registry!

The 2.8.0 registry release has been a long time overdue. This is the first step towards the last 2.x release. No further active development will continue on 2.x branch. Security vulnerability patches to 2.x might be considered, but all active development will be focussed on v3 release due in 2022. This beta release includes a security vulnerability fix along with a few minor bug fixes and improvemnts in documentation and CI.

See changelog below for full list of changes.

Bugfixes

• Close the io.ReadCloser from storage driver #3370
• Remove empty Content-Type header #3297
• Make ipfilteredby not required in cloudfront storage middleware #3088

Features

• Add reference.ParseDockerRef utility function #3002

CI build

• First draft of actions based ci #3347
• Fix vndr and check #3001
• Improve code quality by adding linter checks #3385

Documentation

• Add redirect for old URL #3197 …

Welcome to the v2.7.1 release of registry!

The first patch release of 2.7 addresses an upgrade issue when using configurations from pre-2.7 registries. When upgrading from 2.6 or earlier use this patch release or newer to avoid a failure on startup from not updating the configuration file.

• Set default for new autoredirect option
• GCS driver is now included in binary builds using Dockerfile

Please try out the release binaries and report any issues at https://github.com/docker/distribution/issues.

Contributors

• Derek McGowan
• Ryan Abrams
• David Wu

Changes

• 2461543d Merge pull request #2824 from dmcgowan/update-version-file-2.7.1
• 5b98226a Update version file for 2.7.1
• 2eab12df Merge pull request #2805 from dmcgowan/release-2.7.1
• 445ef068 Release notes for 2.7.1 …

Welcome to the v2.7.0 release of registry!

The 2.7 registry release has been a long time coming and represents both a long gap since the previous release and a renewed effort to release regularly. The maintainers were committed to get OCI support into the next release and thanks to much effort in the community that has been accomplished.

OCI Support

Push and Pull of OCI Images

The registry now allows pushing and pulling OCI images. OCI images will always be preserved exactly without conversion to older types. With this change, clients which implement OCI can feel comfortable creating OCI images as part of their container image build process.

Specification Donation

The Distribution specification which has had 4 years of review, implementation, and production use is now part of OCI. As part of that move, specification changes will no longer be accepted in the open source registry and should instead go to OCI's distribution-spec.

Bug Fixes and Improvements

General

• Update Go version to 1.11
• Switch to multi-stage Dockerfile
• Validations enabled by default with new disabled config option
• Optimize health check performance
• Create separate permission for deleting objects in a repo
• Fix storage driver error propagation for manifest GETs
• Fix forwarded header resolution
• Add prometheus metrics …

Welcome to the v2.7.0-rc.0 release of registry! This is a pre-release of registry

The 2.7 registry release has been a long time coming and represents both a long gap since the previous release and a renewed effort to release regularly. The maintainers were committed to get OCI support into the next release and thanks to much effort in the community that has been accomplished.

OCI Support

Push and Pull of OCI Images

The registry now allows pushing and pulling OCI images. OCI images will always be preserved exactly without conversion to older types. With this change, clients which implement OCI can feel comfortable creating OCI images as part of their container image build process.

Specification Donation

The Distribution specification which has had 4 years of review, implementation, and production use is now part of OCI. As part of that move, specification changes will no longer be accepted in the open source registry and should instead go to OCI's distribution-spec.

Bug fixes

Many many fixes and improvements, see the change log below

Please try out the release binaries and report any issues at https://github.com/docker/distribution/issues.

Contributors

• Derek McGowan
• Stephen J Day
• Olivier Gambier
• Mike Brown
• Aaron Lehmann
• David Wu
• Manish Tomar
• Misty Stanley-Jones
• Sargun Dhillon
• fate-grand-order
• Huu Nguyen
• Yu Wang …