Purging Assets

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

1. An out-of-date or unwanted asset is being served through your Imgix Source (e.g. need to remove for DMCA compliance).
2. You want to update an asset in your Source, but renaming the file is not an option.

Purging does not remove assets 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 asset on occasion. Please contact Support if you need help with purging operations.

Making a Purge Request

Purging removes the asset (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 Origin Image in your Source remains untouched by the purge operation.

1. Remove or replace the asset in your Origin before triggering a purge request. All of the subsequent validation steps depend on your Origin Image status being changed.

2. Call the Purge API using just the base path to the asset, 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 asset, 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 asset again.

   • If you removed the asset, you should receive a 404 error.
   • If you replaced the asset, 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 asset, please visit the following Imgix blog post: What Happens When You Purge an Asset

Purge Request Methods

Purging from the Dashboard

Using the Tools view in the Imgix Dashboard is the easiest way to purge an asset. Simply paste the Imgix URL of the asset you want to purge in the text box in the Purge Single Asset 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 asset. 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 asset you want to purge, into the example below.

POST /api/v1/purge HTTP/1.1
Host: api.imgix.com
Content-Type: application/vnd.api+json
Authorization: Bearer <api-key>
 
{
  "data": {
    "attributes": {
      "url": "<url-to-purge>",
      "source_id": "<source-id>"
    },
    "type": "purges"
  }
} 

Purging Sub-Images

Images used as a mark or a blend (also called a “sub-image”) need to be purged by:

• Including the sub-image: true attribute
• Including the sub-image as a parameter in the URL attribute

Example request:

POST /api/v1/purge HTTP/1.1
Host: api.imgix.com
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
 
{
  "data": {
  "attributes": {
      "url": "<url-to-purge>?mark=<mark-image>&blend=<blend-image>",
      "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.

Purging Assets Served With Long-Form Video

If you are serving and streaming video using Long-Form Video, the purging service and tools will not work for your video assets.

Instead, to remove or update a video on your site, you can:

• Remove the video from your Origin which will take the video down within 72 hours.
  • To speed up video removal, you can use the Management API’s refresh endpoint to refresh the status on a video that has been removed from your Origin.
• In the case of a DMCA takedown, contact support@imgix.com to take down the video.

Troubleshooting

After performing a purge, you may notice that your changes do not immediately appear. Here are some common troubleshooting tips to help:

Changes Are Not Showing

If you’ve successfully purged an asset but the updated content is not displaying:

• Clear your browser cache: Browsers often retain cached versions of images. Clearing the cache ensures the latest asset version is fetched.
• Use an incognito/private tab: This mode bypasses most cache mechanisms and can help verify whether the purge was successful.
• Confirm the correct asset URL: Make sure the URL you are checking matches exactly what was purged.

Web Folder or Web Proxy Sources Show HTML Instead of Image

Assets coming from Web Folder or Web Proxy sources behave differently:

• Imgix fetches content directly from the origin URL and returns it as-is.
• If the origin responds with an HTML page (e.g., an error page or directory listing), Imgix will still return it with a 200 OK status code.
• This is expected behavior, and typically indicates that the requested asset does not exist or the origin is misconfigured.

To resolve this, verify that the file exists at the origin URL and returns the correct image MIME type. If an HTML response is not desired, it’s best to return an error instead.

Purging When a CDN Is in Front of Imgix

When using a content delivery network (CDN) in front of Imgix, it’s important to recognize that both the CDN and Imgix maintain their own cache layers. In such configurations, purging Imgix alone may not yield the desired results if stale content is still being served by the upstream CDN.

To ensure a complete and effective cache invalidation, follow this purge order:

1. Purge the CDN cache first. This step clears the cached asset from the edge locations closest to your users. Most CDNs provide an API or web interface to invalidate specific URLs or path patterns.

2. Purge the Imgix cache. After clearing the CDN, purge the asset from Imgix either via the Purge API or through the Imgix Dashboard. This ensures that any cache within Imgix’s infrastructure is also refreshed.

If you purge Imgix before the CDN:

• The CDN may still serve the old version from its edge caches.
• Your updated content won’t propagate immediately to users, causing confusion or visual inconsistencies.

By reversing the order, you ensure that once Imgix fetches the updated asset, the CDN receives and distributes the latest version across its network.

If you’re still experiencing issues, feel free to contact support.