Deprecation notice: support for older Docker image manifests (schema 1) is ending

[#1]

Hi everyone,

As part of keeping Bitbucket Pipelines secure, we are patching and upgrading the platform that runs your builds. One step in that work changes how a very old Docker image format is handled, and a small number of pipelines will need a quick update. We want to give you clear notice and an easy path forward, so here is what is happening, who it affects, and what to do.

Why this is changing

We continuously patch and upgrade Bitbucket Pipelines infrastructure to keep it secure. Part of that is keeping the operating system, Kubernetes, and the container runtime on current, supported versions.

As part of that ongoing work, we are upgrading the container runtime, containerd, to its current release. The updated release, containerd 2.1, has removed support for an old image format, the Docker image manifest version 1, also called schema 1. Keeping our components current is how we keep the platform secure, and moving to this release means the Pipeline infrastructure no longer pulls schema 1 images.

This format has been on the way out across the container ecosystem for years. Docker deprecated it in v19.03, disabled it by default in v26.0, and removed it in v28.2, and containerd removed it in 2.1. Images built with any recent version of Docker already use the supported formats, OCI or Docker schema 2, so for the vast majority of pipelines this change is invisible.

What is changing

Once your build runs on the upgraded platform, an image that still uses the schema 1 manifest can no longer be pulled. The step fails at the image pull stage with an error like this:

Container 'build' failed to pull image: 'rpc error: code = InvalidArgument desc = failed to pull and unpack image "<image>": schema 1 image manifests are no longer supported: invalid argument'

This applies to the image your step runs on, any services: images you define, and any image you pull or build inside a step.

Who is affected

Most teams are not affected. You are only affected if a pipeline uses an old image that has not been rebuilt in a long time. The cases we see most often are dated language base images and small utility images that have not been updated in years.

If your images are built with a recent version of Docker, your builds will keep working and there is nothing for you to do.

How to tell if this affects you. If a build starts failing with the error above, the image named in the message is the one that needs updating.

Timeline

To keep Bitbucket Pipelines secure for everyone, this change takes effect on 18th July 2026. If one of your images is affected, we would encourage you to update it before then. We are rolling the change out gradually from that date rather than all at once, so the impact stays contained and easy to spot early.

Date (UTC)	What happens
3 July 2026	This notice is published. Your pipelines are not affected yet, and this is a good time to rebuild any old images.
18 July 2026	The change takes effect. From this date, schema 1 images can no longer be pulled. We roll this out gradually across the fleet, so the effect appears over the following days.

What you need to do

If a pipeline of yours uses an older image, the fix is usually quick.

1. Rebuild the image with a current version of Docker. Docker disabled schema 1 by default in v26.0 and removed it in v28.2, so a rebuild with any current Docker produces a supported manifest. Then push it to your registry. If you want to confirm the format, docker manifest inspect your-image:tag shows the mediaType, which should be an OCI or Docker schema 2 type rather than schema 1.

2. If you do not own the image, switch to a maintained equivalent or a current official base image.

3. Re-run your pipeline to confirm the image pulls and the build passes.

For background on the formats, see the Docker Engine deprecated features documentation for the schema 1 timeline and the OCI image specification for the current standard.

What happens if you do nothing

After 18 July 2026, any step that pulls a schema 1 image will fail at the pull stage until that image is rebuilt and pushed in a supported format. Builds that do not use such images are not affected.

Questions or concerns

We know that changes to your build environment can be disruptive, and keeping the platform patched and secure is something we take seriously on your behalf. If you are unsure whether you are affected, or you hit any trouble after rebuilding, reach out to support or leave a comment here and we will help you work it through. We will be watching this space and responding throughout the rollout.

Thank you for helping us keep Bitbucket Pipelines secure and current.