Amazon CloudFront
Developer Guide (API Version 2014-11-06)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

Serving Compressed Files

Amazon CloudFront can serve both compressed and uncompressed files from an origin server. CloudFront relies on the origin server either to compress the files or to have compressed and uncompressed versions of files available; CloudFront does not perform the compression on behalf of the origin server. With some qualifications, CloudFront can also serve compressed content from Amazon S3. For more information, see Choosing the File Types to Compress.

Serving compressed content makes downloads faster because the files are smaller—in some cases, less than half the size of the original. Especially for JavaScript and CSS files, faster downloads translates into faster rendering of web pages for your users. In addition, because the cost of CloudFront data transfer is based on the total amount of data served, serving compressed files is less expensive than serving uncompressed files.

CloudFront can only serve compressed data if the viewer (for example, a web browser or media player) requests compressed content by including Accept-Encoding: gzip in the request header. The content must be compressed using gzip; other compression algorithms are not supported. If the request header includes additional content encodings, for example, deflate or sdch, CloudFront removes them before forwarding the request to the origin server. If gzip is missing from the Accept-Encoding field, CloudFront serves only the uncompressed version of the file. For more information about the Accept-Encoding request-header field, see "Section 14.3 Accept Encoding" in Hypertext Transfer Protocol -- HTTP/1.1 at

For more information, see the following topics:

How CloudFront Serves Compressed Content from a Custom Origin

Here's how CloudFront commonly serves compressed content from a custom origin to a web application:

  1. You configure your web server to compress selected file types. For more information, see Choosing the File Types to Compress.

  2. You create a CloudFront distribution.

  3. You program your web application to access files using CloudFront URLs.

  4. A user accesses your application in a web browser.

  5. CloudFront directs web requests to the edge location that has the lowest latency for the user, which may or may not be the geographically closest edge location.

  6. At the edge location, CloudFront checks the cache for the object referenced in each request. If the browser included Accept-Encoding: gzip in the request header, CloudFront checks for a compressed version of the file. If not, CloudFront checks for an uncompressed version.

  7. If the file is in the cache, CloudFront returns the file to the web browser. If the file is not in the cache:

    1. CloudFront forwards the request to the origin server.

    2. If the request is for a type of file that you want to serve compressed (see Step 1), the web server compresses the file.

    3. The web server returns the file (compressed or uncompressed, as applicable) to CloudFront.

    4. CloudFront adds the file to the cache and serves the file to the user's browser.

Serving Compressed Files from Amazon S3

If you want to serve compressed files from Amazon S3:

  1. Create two versions of each file, one compressed and one uncompressed. To ensure that the compressed and uncompressed versions of a file don't overwrite one another in the CloudFront cache, give each file a unique name, for example, welcome.js and welcome.js.gz.

  2. Open the Amazon S3 console at

  3. Upload both versions to Amazon S3.

    If you're using the Amazon S3 API to upload files, include a Content-Type header to specify the MIME type of each file. The default MIME type is binary/octet-stream.

    If you're using the Amazon S3 console to upload files, Amazon S3 automatically figures out the content types of the files by default.

  4. Add a Content-Encoding header field for each compressed file and set the field value to gzip.

    For an example of how to add a Content-Encoding header field using the AWS SDK for PHP, see Upload an Object Using the AWS SDK for PHP in the Amazon Simple Storage Service Developer Guide. Some third-party tools are also able to add this field.

    To add a Content-Encoding header field and set the field value using the Amazon S3 console, perform the following procedure:

    1. In the Amazon S3 console, in the Buckets pane, click the name of the bucket that contains the compressed files.

    2. Click the name of a file for which you want to add a Content-Encoding header.

    3. At the top of the page, click Actions. In the Actions list, click Properties.

    4. In the right pane, click Metadata.

    5. Under Metadata, click Add More Metadata.

    6. In the Key list, click Content-Encoding.

    7. In the Value field, enter gzip.

    8. Click Save.

    9. Repeat steps 4b through 4h for the remaining compressed files.

  5. When generating HTML that links to content in CloudFront (for example, using php, asp, or jsp), evaluate whether the request from the viewer includes Accept-Encoding: gzip in the request header. If so, rewrite the corresponding link to point to the compressed object name.

Choosing the File Types to Compress

Some types of files compress well, for example, HTML, CSS, and JavaScript files. Some types of files may compress a few percent, but not enough to justify the additional processor cycles required for your web server to compress the content, and some types of files even get larger when they're compressed. File types that generally don't compress well include graphic files that are already compressed (.jpg, .gif), video formats, and audio formats. We recommend that you test compression for the file types in your distribution to ensure that there is sufficient benefit to compression.