Image & Video APIs
Menu

Optimize PDFs

Last updated: Nov-23-2025

Whether you're delivering PDFs from your website, or using Cloudinary to store and share them, PDF compression may be of interest to you. By compressing PDFs, especially if they're image rich, you can benefit from big storage savings and faster download speeds.

Important
PDF optimization is currently available to certain customers only. If you'd like to enable it for your product environment, please contact support.

On this page:

Automatic quality for PDFs

You can optimize the size of your PDFs automatically:

In each case, use the automatic quality transformation (q_auto in URLs), which applies a certain amount of compression to your PDFs, while maintaining visual quality.

Notes
  • Quality types such as best, good, eco etc. aren't yet supported when applying automatic quality to PDFs.
  • For Cloudinary to optimize a PDF, it can't exceed 300 pages or 200 MB in size. If it exceeds either of these limits or takes longer than 120 seconds to process, Cloudinary returns the original instead.
  • Some PDFs, even below these limits, can't be optimized and reduced in size. In these cases, Cloudinary returns the original.
  • PDFs with images typically benefit from better optimization than those without.
  • PDF optimization is intended mainly for on-screen viewing (in a browser or PDF viewer). For high-quality printing, it's best to avoid optimizing the PDF.
  • There's a special transformation count for applying automatic quality to PDFs.

Optimize PDFs on delivery

Important
To reduce the chances of malware or other potentially harmful files being distributed via the Cloudinary domain, PDFs (and certain other file formats) are blocked for delivery by default for FREE accounts. To deliver PDFs, make sure the Allow delivery of PDF and ZIP files option is selected in the Security page of the Console Settings.

If you're storing your original uncompressed PDFs in your Cloudinary product environment, you can deliver compressed PDFs on the fly to your end users without affecting the original copy.

To deliver optimized PDFs, apply the q_auto transformation parameter to your delivery URL, either directly, or using one of our SDKs, as shown:

In this case, the original PDF is 1.8 MB and the optimized PDF is 1.1 MB.

Optimize PDFs on upload

If you want to save on storage, you can optimize PDFs on upload using an incoming transformation. In this case, the compressed version of the PDF is stored in your product environment.

Response:

Optimize previously uploaded PDFs

If you've got original, uncompressed PDFs already in your Cloudinary product environment, and you want to save some storage, you can follow these steps to overwrite an original PDF with an optimized PDF:

  1. Use the original PDF's URL as the upload source.
  2. Apply the automatic quality transformation as an incoming transformation.
  3. Set the public ID to match the existing PDF.
  4. Include the overwrite and invalidate parameters.

For example:

This applies the automatic quality transformation, overwrites the existing asset, and invalidates any cached versions on the CDN.

Related topics

Troubleshooting PDF optimization

If the PDF after optimization is the same size as the original, it may be because:

  • This is the first time you've requested the PDF with q_auto and the optimization didn't complete within 30 seconds. In this case, Cloudinary returns the original and continues processing the PDF for up to another 90 seconds. If successful, the next time you request the PDF with q_auto, Cloudinary returns an optimized version.
  • The PDF exceeds 300 pages or 200 MB, so Cloudinary can't optimize it.
  • Processing takes longer than 120 seconds, so Cloudinary can't optimize it.
  • The PDF is already as optimized as it can be.

✔️ Feedback sent!

Rate this page: