Deprecating the Distribution of Microsoft Container Images via Docker Hub
Published May 19 2021 11:48 AM 14.8K Views


As containers and cloud native workloads continue to grow, ensuring that customers can reliably acquire vendor artifacts becomes crucial. Microsoft is committed to offer its customers reliable and performant experience for pulling Microsoft container images from the Microsoft Container Registry (MCR or MCR contains the full catalog of container images produced by Microsoft with their most up-to-date versions and tags. By leveraging Azure’s global footprint, MCR offers public access to Microsoft’s images globally. With that in mind, we are deprecating all /microsoft org container images hosted in Docker Hub repositories on June 30th, 2021.


How does this impact you?

If you continue to reference Microsoft container images using repositories in Docker Hub, this will have impact on your development, deployment, and automation scripts.

Examples for such references are: FROM microsoft/* in Dockerfile or docker run microsoft/* in automation scripts. You can leverage to discover such references in OSS scripts.

  • Starting June 1st, 2021 pulls of microsoft/ org container images from Docker Hub registry will be throttled according to Docker Terms of Use. This will limit the number of pulls that you are allowed within certain time period.
  • Starting July 1st, 2021 repositories from microsoft/ org on Docker Hub will be removed. At this point development, deployment and automation scripts that still reference microsoft/ org images from Docker Hub registry will fail.

To avoid any impact on your development, deployment or automation scripts, you must update docker pull commands, FROM statements in Dockerfiles, and other references to microsoft/ container images to explicitly reference the registry.

We understand that certain repositories from microsoft/ org on Docker Hub registry are highly trafficked, and customers relying on them may not be able to complete these changes by June 30th, 2021. We are working to identify those repositories and provide extension for them. A list of such repositories and for how long they will be available will be published on MCR’s GitHub repository by June 1st, 2021.


Mapping of Docker Hub repositories to MCR repositories

Mapping between the repository names on Docker Hub and MCR can be found on MCR's GitHub repository.


Guidance for Consuming Public Container Images

Having a controlled workflow for consumption of public content like container images from Docker Hub and MCR is a key for building a secured and reliable software supply chain. Please see the Open Container Initiative’s Consuming Public Content for general guidance and Azure’s guidance for consuming public content.



Back in 2018, we announced the transition of Microsoft container images hosting to MCR with syndication to Docker Hub, which laid the ground for worldwide distribution of Microsoft container images. Last year Docker announced an update of their terms of use and plans for image retention – both changes impacting pulls of container images from Docker Hub. Microsoft and Docker have worked closely to provide smooth transition for customers who need to pull /microsoft org container images. Docker Hub pages were updated to reflect the new pull location,, and are continuously updated with information how to pull up-to-date tags from MCR. We will continue this collaboration to provide an easy and frictionless discoverability mechanism for Microsoft container images through Docker Hub.


How to get additional help?

We understand that there may be unanswered questions. You can get additional help by submitting an issue on GitHub or sending an email to

1 Comment
Version history
Last update:
‎May 19 2021 12:56 PM
Updated by: