`: The JPEG compression quality (1-100) used when writing back lossy images. (Default: 75) * `allow_upscale=`: If true, allows upscaling, so that all images are targeted. If false, downsample only, that is: only target images whose horizontal or vertical resolution exceeds the `dpi` value. * `allow_growth=`: If true, allows images to replace originals even if the compressed stream size grows (useful for strict pre-press/compliance). (Default: same as `allow_upscale`) * `force=`: If true, resample images with complex colorspaces (/Indexed, /Separation, /DeviceN, etc.) by converting them to a standard colorspace. The colorspace declaration in the PDF will be updated to match. This may alter colors in palette or spot-color images. (Default: false) **Image types supported:** * Grayscale (/DeviceGray) and color (/DeviceRGB, /DeviceCMYK) images, including those with embedded ICC profiles (/ICCBased) — color profiles are preserved exactly. * Transparency-masked images (soft mask / SMask) — the mask is resized alongside the parent image. * Bitonal (1-bit) images — resampled with nearest-neighbor to avoid introducing gray pixels. **Images that will be skipped:** * Images whose colorspace cannot be safely round-tripped after resize. This includes /Indexed (palette), /Separation (spot color), /DeviceN, /Lab, and other exotic colorspaces. Modifying these would require rewriting the colorspace declaration, which risks breaking color-managed and prepress workflows. Use `force=true` to resample these anyway — the colorspace will be converted and the declaration updated. A debug log entry is emitted for each skipped image. * Images where the recompressed stream would be larger than the original (unless `allow_growth=true` is set). **How DPI is determined:** * DPI is calculated from the image's rendered size on the page, not from metadata embedded in the image. An image is only resampled when its effective horizontal or vertical DPI exceeds the target threshold. * For image objects that are used only once, resampling is based on that placement's effective DPI. * PDF image objects may be shared and reused at multiple sizes throughout a document. Shared image objects are processed only once. When the same image appears at multiple scales, the first placement encountered is used to determine the target resolution, and the resulting effective DPI may differ between placements. **Behavior and guarantees:** * Shared image XObjects are processed only once, even if they appear on multiple pages. This avoids repeatedly recompressing the same PDF object. * Embedded ICC color profiles are preserved whenever the image colorspace can be safely round-tripped. This helps maintain color fidelity in color-managed workflows. * Soft masks (/SMask) are resized alongside their parent images so transparency remains aligned. * Bitonal (1-bit) images are resized using nearest-neighbor resampling to avoid introducing gray pixels into black-and-white scans, text, or line art. * By default, images are only replaced if the resulting compressed stream is smaller than the original. Use `allow_growth=true` to prioritize DPI compliance over file size. **Limitations:** * A single PDF image object may be reused at different sizes throughout the document. Because PDF image objects are shared resources, the operation can only store one pixel resolution for that image. When a shared image appears at multiple scales, the resulting effective DPI may differ between placements after resampling. * JPEG images are decoded, resized, and re-encoded when resampling is required. Original JPEG quantization tables, chroma subsampling settings, and progressive encoding are not preserved. * Inline images embedded directly inside page content streams are not currently targeted. ## Examples > Resample all eligible images globally to max 150 DPI. ``` pdftl in.pdf resample_images output out.pdf ``` > Resample images on pages 1-5 to 72 DPI with aggressive compression. ``` pdftl in.pdf resample_images 1-5 dpi=72 quality=60 output out.pdf ``` > Resample all images including indexed and spot-color, converting colorspaces. ``` pdftl in.pdf resample_images force=true output out.pdf ``` **Tags**: in_place, images, optimization *Source: pdftl.operations.resample_images* *Read online: [https://pdftl.readthedocs.io/en/latest/operations/resample_images.html](https://pdftl.readthedocs.io/en/latest/operations/resample_images.html)* *Type: Operation*