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, but renaming the file is not an option.

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.

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 quickly, but we do not guarantee a completion time, so testing is highly recommended.

For more under the hood information on what happens when you Purge an image, please visit the following imgix blog post: What Happens When You Purge an Image

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.

Please make sure to encode unsafe ASCII characters prior to purging. URL encoding replaces unsafe ASCII characters with a "%" followed by two hexadecimal digits. For example, if your file name contains a space, please make sure to replace the space with a %20. (e.g. https://assets.imgix.net/image file.png should be changed to: https://assets.imgix.net/image%20file.png)

Assets will be purged at the exact path that is specified. The example above will purge https://assets.imgix.net/image%20file.png, but will not purge https://assets.imgix.net/image+file.png.

Purging with curl

If you're comfortable using the command line, it's the fastest way to purge an image. First, find or create an API key on the API Keys page. The API key must have the Purge permission. Then simply plug it, and the URL of the image you want to purge, into the example below.

curl -X POST 'https://api.imgix.com/api/v1/purge' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/vnd.api+json' \
  --data-raw '{ "data": { "attributes": { "url": "<url-to-purge>" }, "type": "purges" } }'

Purging with Python

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

import requests
import json
API_KEY = ""  # API key can be found at https://dashboard.imgix.com/api-keys
API_ENDPOINT = "https://api.imgix.com/api/v1/purge"
imgix_url = "https://assets.imgix.net/examples/couple.jpg"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/vnd.api+json",
}
payload = {
    "data": {
        "type": "purges",
        "attributes": {
            "url": imgix_url,
            "source_id": "5ebee107e9c05c0001d9c2d3",
            "sub_image": False,
        }
    }
}
requests.post(url=API_ENDPOINT, headers=headers, data=json.dumps(payload))

Purging Sub-Images

Images used as a mark or a blend (also called a "sub-image") need to be purged by including sub-image attributes. The example below performs a purge on the sub-image through the command line.

curl -X POST 'https://api.imgix.com/api/v1/purge' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'Authorization: Bearer <api-key>' \
  --data-raw '{ "data": { "attributes": { "url": "<url-to-purge>", "sub_image": true, "source_id": "<source-id>" }, "type": "purges" } }'

You can read more about the Purging API and see more examples in the Purge API documentation.

Next: Account Setup & Analytics