Purging container images from Azure Container Registry

Tobias Zimmergren
Tobias Zimmergren

Keeping container registries clean and neat is not always an easy task. We have fairly agile release processes, and sometimes we release many images, several times per day across dev- and production environments.

Microsoft recently introduced a neat way to automatically purge images based on filters, directly from the Azure CLI.

Use cases

I saw an immense growth in the Azure Container Registry size. Tags, experimental features, legacy releases, and more - everything we ever pushed to ACR is just sitting there. Most of it is doing nothing.

Seeing this, I created a set of utility scripts that could help me clean things up, but they weren't ideal. I had to construct them carefully to cater to my specific filters for what I needed to remove. It got the job done, but also required some maintenance, and testing - we don't want to accidentally remove production workloads because of mistakes in our workflow.

Enter ACR purge!

Some of my use cases include the ones below. I am certain there's plenty more. Feel free to leave a comment with your scenarios.

Use case: Date-based retention

Deploying multiple times per day, week or month is great. However, when you have a lot of images, and each image have a plethora of tags and versions, it quickly grows beyond maintainability.

In most of my scenarios, there are no reasons for me to keep images that are older than 6 months. When something needs a roll-back, we're talking about hours, or days. Not weeks or months.

Therefore, date-based retention is a great way to keep my registries clean. You can specify any time frame when you want to purge old images.

Use case: Clean up preview, beta, or other short-lived images

Should we want to filter on something other than the date, we can of course also purge images based on specific tags.

Sometimes we push new features, preview-functionality or separate branches. When this happens, we end up with many different images with a lot of different tags.

When a specific test or feature exploration is done, we can safely remove those images again because we are sure to not need them again - usually after these changes are merged back into the main branch and released into the production services and workloads.

With this, we can for example purge all tags matching my-image:preview-1.2.3, or whatever else we want. With the acr purge command, we can also specify the filter with regular expressions, which allows us to do a wider-scoped purge based on regex patterns.

Use case: Run on a schedule

While the aforementioned ways to clean up is great, I often do them manually. With the acr purge capabilities, we can also schedule the purge to run automatically on a specific schedule.

This is based on running ACR tasks. Check out the links in the end of this post for how to set those things up. It's neat!

Using ACR purge

While not re-iterating what's already documented, here's how to run the ACR purge command, and the output to expect.

Warning: Before you use this command, please read the docs as mentioned in the end of this post, and understand the warnings.

I ensure I'm signed in with the correct account using az login, and then I explicitly set the subscription I want to target:

az account set -s 12341234-feed-deef-feed-123412341234

Now I can target my ACR, and start a purge. In my example, I'm purging anything older than 30 days, and also purge all untagged images.

az acr run --cmd "acr purge --filter 'my-image:.*' --ago 30d --untagged" --registry mycontainerregistry /dev/null

When the task kicks off, you'll see that the CLI will queue the job for an agent, and upon availability, the job kicks off.

Azure Container Registry (ACR) purge using acr tasks.

When the task is completed, you'll get the stats on-screen.

ACR purge executed successfully.


I like to keep things clean and tidy, and foremost I want to have full insights and maintainability over the systems I operate. Azure Governance is important, and with the introduction of ACR purge, we can have yet another tool in our toolbox that helps with this goal.

Something I haven't covered in this post, is retention policies for untagged manifests. This is a great new capability that come with the Azure CLI 2.0.74 or later - check that out here:

Read more about the usage, and warnings, on the Microsoft docs website:


Tobias Zimmergren Twitter

Hi, I'm Tobias! 👋 I write about Microsoft Azure, security, cybersecurity, compliance, cloud architecture, Microsoft 365, and general tech!

Reactions and mentions

Hi, I'm Tobias 👋

Tobias Zimmergren profile picture

Find out more about me.

Recent comments