Documentation

Purging Images

If you need to remove or update an image on imgix, you can purge it from our caches. Common reasons for purging an image are:

  1. An out-of-date or unwanted image is being served through your imgix Source (e.g. need to remove for DMCA compliance).
  2. You want to update an image in your Source without renaming the file.

Making a Purge Request

Purging removes the image (e.g. https://assets.imgix.net/dogs.png) from our caches, which then clears out all derivatives as well (https://assets.imgix.net/dogs.png?w=400, etc.). The master image in your Source remains untouched by the purge operation.

  1. Remove or replace the image in your Source before triggering a purge request. All of the subsequent validation steps depend on your master image status being changed.
  2. Call the Purge API using just the base path to the image, with no parameters (e.g. you.imgix.net/your-image.png). See Purge Request Methods below for different ways to do this. The request will purge all derivatives of this image, so you don’t have to do each one individually.
    • The API will return a 200 status code if successfully received; this does not mean that the purge has completed yet.
  3. Test the result by fetching the image again.
    • If you removed the image, you should receive a 404 error.
    • If you replaced the image, you should get the updated version.

Purges typically complete through the entire imgix system in <1 minute, but the system does not guarantee a completion time, so testing is highly recommended. To absolutely ensure compliance for an updated image, it’s best to give the image a new path by renaming the file.

Purge Request Methods

Purging from the Dashboard

Using the Tools view in the imgix Dashboard is the easiest way to purge an image. Simply paste the imgix URL of the image you want to purge in the text box in the Purge Single Image section and click Purge.

Screenshot-Purging single image from Dashboard

Purging with curl

If you’re comfortable using the command line, it’s the fastest way to purge an image. First, find your API Key on the Account page. Then simply plug it, and the URL of the image you want to purge, into the example below.

curl "https://api.imgix.com/v2/image/purger" \
  -u "$API_KEY:" \
  -d "url=$URL_TO_PURGE"

Purging with Python

Below is an example of purging an image with Python and the Requests library.

import requests

API_KEY = "" # REPLACE - find your API KEY @ https://dashboard.imgix.com/accounts

def purge_imgix_image(url):
    purge_endpoint = "https://api.imgix.com/v2/image/purger"
    requests.post(purge_endpoint, auth=(API_KEY, ''), data={"url": url})

purge_imgix_image("http://examples.imgix.net/frog.jpg")

What Happens When You Purge an Image

imgix completes several options in sequence when a purge is requested:

  1. The request is revalidated against the image in your Source. If the image is unchanged (returns a 304 status code), then the purge process stops. This is why any changes to an image, such as replacement or removal, have to start with your master image at the Source.
  2. If the image registers as changed, then it’s either removed or replaced by the new version in imgix’s origin cache.
  3. A request is then sent to the imgix CDN to set the image’s TTL to 0s, thus forcing revalidation on subsequent requests for both the master image and all derivatives.

Diagram of purge process

Purging does not remove images from any of the following, because they are outside of the imgix system:

  • Your Source (Amazon S3, Google Cloud Storage, etc.)
  • Any third-party CDNs you might use in addition to the imgix CDN
  • The end user’s browser cache
  • Any ISP caches between imgix and the end user

Because of this, it is still possible for the end user to see an out-of-date image on occasion. Please contact Support if you need help with purging operations.