Image file formats

The Python Imaging Library supports a wide variety of raster file formats.Over 30 different file formats can be identified and read by the library.Write support is less extensive, but most common interchange and presentationformats are supported.

The open() function identifies files from theircontents, not their names, but the save() methodlooks at the name to determine which format to use, unless the format is givenexplicitly.

Fully supported formats

Contents

BMP

Pillow reads and writes Windows and OS/2 BMP files containing 1, L, P,or RGB data. 16-colour images are read as P images. Run-length encodingis not supported.

The open() method sets the followinginfo properties:

  • compression
  • Set to bmp_rle if the file is run-length encoded.

DIB

Pillow reads and writes DIB files. DIB files are similar to BMP files, so seeabove for more information.



New in version 6.0.0.



EPS

Pillow identifies EPS files containing image data, and can read files thatcontain embedded raster images (ImageData descriptors). If Ghostscript isavailable, other EPS files can be read as well. The EPS driver can also writeEPS images. The EPS driver can read EPS images in L, LAB, RGB andCMYK mode, but Ghostscript may convert the images to RGB mode ratherthan leaving them in the original color space. The EPS driver can write imagesin L, RGB and CMYK modes.

If Ghostscript is available, you can call the load()method with the following parameter to affect how Ghostscript renders the EPS

  • scale
  • Affects the scale of the resultant rasterized image. If the EPS suggeststhat the image be rendered at 100px x 100px, setting this parameter to2 will make the Ghostscript render a 200px x 200px image instead. Therelative position of the bounding box is maintained:
  1. im = Image.open(...)
  2. im.size #(100,100)
  3. im.load(scale=2)
  4. im.size #(200,200)

GIF

Pillow reads GIF87a and GIF89a versions of the GIF file format. The librarywrites run-length encoded files in GIF87a by default, unless GIF89a featuresare used or GIF89a is already in use.

Note that GIF files are always read as grayscale (L)or palette mode (P) images.

The open() method sets the followinginfo properties:

  • background
  • Default background color (a palette color index).
  • transparency
  • Transparency color index. This key is omitted if the image is nottransparent.
  • version
  • Version (either GIF87a or GIF89a).
  • duration
  • May not be present. The time to display the current frameof the GIF, in milliseconds.
  • loop
  • May not be present. The number of times the GIF should loop. 0 means thatit will loop forever.
  • comment
  • May not be present. A comment about the image.
  • extension
  • May not be present. Contains application specific information.

Reading sequences

The GIF loader supports the seek() andtell() methods. You can combine these methodsto seek to the next frame (im.seek(im.tell() + 1)).

im.seek() raises an EOFError if you try to seek after the last frame.

Saving

When calling save() to write a GIF file, thefollowing options are available:

  1. im.save(out, save_all=True, append_images=[im1, im2, ...])
  • save_all
  • If present and true, all frames of the image will be saved. Ifnot, then only the first frame of a multiframe image will be saved.
  • append_images
  • A list of images to append as additional frames. Each of theimages in the list can be single or multiframe images.This is currently supported for GIF, PDF, TIFF, and WebP.

It is also supported for ICNS. If images are passed in of relevant sizes,they will be used instead of scaling down the main image.

  • include_color_table
  • Whether or not to include local color table.
  • interlace
  • Whether or not the image is interlaced. By default, it is, unless the imageis less than 16 pixels in width or height.
  • disposal

  • Indicates the way in which the graphic is to be treated after being displayed.

    • 0 - No disposal specified.
    • 1 - Do not dispose.
    • 2 - Restore to background color.
    • 3 - Restore to previous content.

Pass a single integer for a constant disposal, or a list or tuple
to set the disposal for each frame separately.
  • palette
  • Use the specified palette for the saved image. The palette shouldbe a bytes or bytearray object containing the palette entries inRGBRGB… form. It should be no more than 768 bytes. Alternately,the palette can be passed in as anPIL.ImagePalette.ImagePalette object.
  • optimize
  • If present and true, attempt to compress the palette byeliminating unused colors. This is only useful if the palette canbe compressed to the next smaller power of 2 elements.

Note that if the image you are saving comes from an existing GIF, it may havethe following properties in its info dictionary.For these options, if you do not pass them in, they will default totheir info values.

  • transparency
  • Transparency color index.
  • duration
  • The display duration of each frame of the multiframe gif, inmilliseconds. Pass a single integer for a constant duration, or alist or tuple to set the duration for each frame separately.
  • loop
  • Integer number of times the GIF should loop. 0 means that it will loopforever. By default, the image will not loop.
  • comment
  • A comment about the image.

Reading local images

The GIF loader creates an image memory the same size as the GIF file’s logicalscreen size, and pastes the actual pixel data (the local image) into thisimage. If you only want the actual pixel rectangle, you can manipulate thesize and tileattributes before loading the file:

  1. im = Image.open(...)
  2.  
  3. if im.tile[0][0] == "gif":
  4.     # only read the first "local image" from this GIF file
  5.     tag, (x0, y0, x1, y1), offset, extra = im.tile[0]
  6.     im.size = (x1 - x0, y1 - y0)
  7.     im.tile = [(tag, (0, 0) + im.size, offset, extra)]

ICNS

Pillow reads and (macOS only) writes macOS .icns files. By default, thelargest available icon is read, though you can override this by setting thesize property before callingload(). The open() methodsets the following info property:

  • sizes
  • A list of supported sizes found in this icon file; these are a3-tuple, (width, height, scale), where scale is 2 for a retinaicon and 1 for a standard icon. You are permitted to use this 3-tupleformat for the size property if you set itbefore calling load(); after loading, the sizewill be reset to a 2-tuple containing pixel dimensions (so, e.g. if youask for (512, 512, 2), the final value ofsize will be (1024, 1024)).

The save() method can take the following keyword arguments:

  • append_images
  • A list of images to replace the scaled down versions of the image.The order of the images does not matter, as their use is determined bythe size of each image.

New in version 5.1.0.

ICO

ICO is used to store icons on Windows. The largest available icon is read.

The save() method supports the following options:

  • sizes
  • A list of sizes including in this ico file; these are a 2-tuple,(width, height); Default to [(16, 16), (24, 24), (32, 32), (48, 48),
    (64, 64), (128, 128), (256, 256)]    . Any sizes bigger than the originalsize or 256 will be ignored.

IM

IM is a format used by LabEye and other applications based on the IFUNC imageprocessing library. The library reads and writes most uncompressed interchangeversions of this format.

IM is the only format that can store all internal Pillow formats.

JPEG

Pillow reads JPEG, JFIF, and Adobe JPEG files containing L, RGB, orCMYK data. It writes standard and progressive JFIF files.

Using the draft() method, you can speed things up byconverting RGB images to L, and resize images to 1/2, 1/4 or 1/8 oftheir original size while loading them.

The open() method may set the followinginfo properties if available:

  • jfif
  • JFIF application marker found. If the file is not a JFIF file, this key isnot present.
  • jfif_version
  • A tuple representing the jfif version, (major version, minor version).
  • jfif_density
  • A tuple representing the pixel density of the image, in units specifiedby jfif_unit.
  • jfif_unit

  • Units for the jfif_density:

    • 0 - No Units
    • 1 - Pixels per Inch
    • 2 - Pixels per Centimeter
  • dpi
  • A tuple representing the reported pixel density in pixels per inch, ifthe file is a jfif file and the units are in inches.
  • adobe
  • Adobe application marker found. If the file is not an Adobe JPEG file, thiskey is not present.
  • adobe_transform
  • Vendor Specific Tag.
  • progression
  • Indicates that this is a progressive JPEG file.
  • icc_profile
  • The ICC color profile for the image.
  • exif
  • Raw EXIF data from the image.
  • comment
  • A comment about the image.

New in version 7.1.0.

The save() method supports the following options:

  • quality
  • The image quality, on a scale from 0 (worst) to 95 (best). The default is75. Values above 95 should be avoided; 100 disables portions of the JPEGcompression algorithm, and results in large files with hardly any gain inimage quality.
  • optimize
  • If present and true, indicates that the encoder should make an extra passover the image in order to select optimal encoder settings.
  • progressive
  • If present and true, indicates that this image should be stored as aprogressive JPEG file.
  • dpi
  • A tuple of integers representing the pixel density, (x,y).
  • icc_profile
  • If present and true, the image is stored with the provided ICC profile.If this parameter is not provided, the image will be saved with no profileattached. To preserve the existing profile:
  1. im.save(filename, 'jpeg', icc_profile=im.info.get('icc_profile'))
  • exif
  • If present, the image will be stored with the provided raw EXIF data.
  • subsampling

  • If present, sets the subsampling for the encoder.

    • keep: Only valid for JPEG files, will retain the original image setting.
    • 4:4:4, 4:2:2, 4:2:0: Specific sampling values
    • -1: equivalent to keep
    • 0: equivalent to 4:4:4
    • 1: equivalent to 4:2:2
    • 2: equivalent to 4:2:0
  • qtables

  • If present, sets the qtables for the encoder. This is listed as anadvanced option for wizards in the JPEG documentation. Use withcaution. qtables can be one of several types of values:

    • a string, naming a preset, e.g. keep, web_low, or web_high
    • a list, tuple, or dictionary (with integer keys =range(len(keys))) of lists of 64 integers. There must bebetween 2 and 4 tables.

New in version 2.5.0.

Note

To enable JPEG support, you need to build and install the IJG JPEG librarybefore building the Python Imaging Library. See the distribution README fordetails.

JPEG 2000

New in version 2.4.0.

Pillow reads and writes JPEG 2000 files containing L, LA, RGB orRGBA data. It can also read files containing YCbCr data, which itconverts on read into RGB or RGBA depending on whether or not there isan alpha channel. Pillow supports JPEG 2000 raw codestreams (.j2k files),as well as boxed JPEG 2000 files (.j2p or .jpx files). Pillow doesnot support files whose components have different sampling frequencies.

When loading, if you set the mode on the image prior to theload() method being invoked, you can ask Pillow toconvert the image to either RGB or RGBA rather than choosing foritself. It is also possible to set reduce to the number of resolutions todiscard (each one reduces the size of the resulting image by a factor of 2),and layers to specify the number of quality layers to load.

The save() method supports the following options:

  • offset
  • The image offset, as a tuple of integers, e.g. (16, 16)
  • tile_offset
  • The tile offset, again as a 2-tuple of integers.
  • tile_size
  • The tile size as a 2-tuple. If not specified, or if set to None, theimage will be saved without tiling.
  • quality_mode
  • Either "rates" or "dB" depending on the units you want to use tospecify image quality.
  • quality_layers
  • A sequence of numbers, each of which represents either an approximate sizereduction (if quality mode is "rates") or a signal to noise ratio valuein decibels. If not specified, defaults to a single layer of full quality.
  • num_resolutions
  • The number of different image resolutions to be stored (which correspondsto the number of Discrete Wavelet Transform decompositions plus one).
  • codeblock_size
  • The code-block size as a 2-tuple. Minimum size is 4 x 4, maximum is 1024 x1024, with the additional restriction that no code-block may have morethan 4096 coefficients (i.e. the product of the two numbers must be nogreater than 4096).
  • precinct_size
  • The precinct size as a 2-tuple. Must be a power of two along both axes,and must be greater than the code-block size.
  • irreversible
  • If True, use the lossy Irreversible Color Transformationfollowed by DWT 9-7. Defaults to False, which means to use theReversible Color Transformation with DWT 5-3.
  • progression
  • Controls the progression order; must be one of "LRCP", "RLCP","RPCL", "PCRL", "CPRL". The letters stand for Component,Position, Resolution and Layer respectively and control the order ofencoding, the idea being that e.g. an image encoded using LRCP mode canhave its quality layers decoded as they arrive at the decoder, while oneencoded using RLCP mode will have increasing resolutions decoded as theyarrive, and so on.
  • cinema_mode
  • Set the encoder to produce output compliant with the digital cinemaspecifications. The options here are "no" (the default),"cinema2k-24" for 24fps 2K, "cinema2k-48" for 48fps 2K, and"cinema4k-24" for 24fps 4K. Note that for compliant 2K files,at least one of your image dimensions must match 2048 x 1080, whilefor compliant 4K files, at least one of the dimensions must match4096 x 2160.

Note

To enable JPEG 2000 support, you need to build and install the OpenJPEGlibrary, version 2.0.0 or higher, before building the Python ImagingLibrary.

Windows users can install the OpenJPEG binaries available on theOpenJPEG website, but must add them to their PATH in order to use Pillow (ifyou fail to do this, you will get errors about not being able to load the_imaging DLL).

MSP

Pillow identifies and reads MSP files from Windows 1 and 2. The library writesuncompressed (Windows 1) versions of this format.

PCX

Pillow reads and writes PCX files containing 1, L, P, or RGB data.

PNG

Pillow identifies, reads, and writes PNG files containing 1, L, LA,I, P, RGB or RGBA data. Interlaced files are supported as ofv1.1.7.

As of Pillow 6.0, EXIF data can be read from PNG images. However, unlike otherimage formats, EXIF data is not guaranteed to be present ininfo until load() has beencalled.

The open() method sets the followinginfo properties, when appropriate:

  • chromaticity
  • The chromaticity points, as an 8 tuple of floats. (White Point
    X    , White Point Y, Red X, Red Y, Green X, Green
    Y    , Blue X, Blue Y)
  • gamma
  • Gamma, given as a floating point number.
  • srgb
  • The sRGB rendering intent as an integer.


  • 0 Perceptual

  • 1 Relative Colorimetric

  • 2 Saturation

  • 3 Absolute Colorimetric


  • transparency
  • For P images: Either the palette index for full transparent pixels,or a byte string with alpha values for each palette entry.

For 1, L, I and RGB images, the color that representsfull transparent pixels in this image.

This key is omitted if the image is not a transparent palette image.

open also sets Image.text to a dictionary of the values of thetEXt, zTXt, and iTXt chunks of the PNG image. Individualcompressed chunks are limited to a decompressed size ofPngImagePlugin.MAX_TEXT_CHUNK, by default 1MB, to preventdecompression bombs. Additionally, the total size of all of the textchunks is limited to PngImagePlugin.MAX_TEXT_MEMORY, defaulting to64MB.

The save() method supports the following options:

  • optimize
  • If present and true, instructs the PNG writer to make the output file assmall as possible. This includes extra processing in order to find optimalencoder settings.
  • transparency
  • For P, 1, L, I, and RGB images, this option controlswhat color from the image to mark as transparent.

For P images, this can be a either the palette index,or a byte string with alpha values for each palette entry.

  • dpi
  • A tuple of two numbers corresponding to the desired dpi in each direction.
  • pnginfo
  • A PIL.PngImagePlugin.PngInfo instance containing text tags.
  • compress_level
  • ZLIB compression level, a number between 0 and 9: 1 gives best speed,9 gives best compression, 0 gives no compression at all. Default is 6.When optimize option is True compress_level has no effect(it is set to 9 regardless of a value passed).
  • icc_profile
  • The ICC Profile to include in the saved file.
  • exif
  • The exif data to include in the saved file.

New in version 6.0.0.

  • bits (experimental)
  • For P images, this option controls how many bits to store. If omitted,the PNG writer uses 8 bits (256 colors).
  • dictionary (experimental)
  • Set the ZLIB encoder dictionary.

Note

To enable PNG support, you need to build and install the ZLIB compressionlibrary before building the Python Imaging Library. See the installationdocumentation for details.

APNG sequences

The PNG loader includes limited support for reading and writing Animated PortableNetwork Graphics (APNG) files.When an APNG file is loaded, get_format_mimetype()will return "image/apng". The value of the is_animatedproperty will be True when the n_frames property isgreater than 1. For APNG files, the n_frames property depends on both the animationframe count as well as the presence or absence of a default image. See thedefault_image property documentation below for more details.The seek() and tell() methodsare supported.

im.seek() raises an EOFError if you try to seek after the last frame.

These info properties will be set for APNG frames,where applicable:

  • default_image
  • Specifies whether or not this APNG file contains a separate default image,which is not a part of the actual APNG animation.

When an APNG file contains a default image, the initially loaded image (i.e.the result of seek(0)) will be the default image.To account for the presence of the default image, then_frames property will be set to frame_count + 1,where frame_count is the actual APNG animation frame count.To load the first APNG animation frame, seek(1) must be called.

  • True - The APNG contains default image, which is not an animation frame.
  • False - The APNG does not contain a default image. The n_frames propertywill be set to the actual APNG animation frame count.The initially loaded image (i.e. seek(0)) will be the first APNG animationframe.
    • loop
    • The number of times to loop this APNG, 0 indicates infinite looping.
    • duration
    • The time to display this APNG frame (in milliseconds).

Note

The APNG loader returns images the same size as the APNG file’s logical screen size.The returned image contains the pixel data for a given frame, after applyingany APNG frame disposal and frame blend operations (i.e. it contains what a webbrowser would render for this frame - the composite of all previous frames and thisframe).

Any APNG file containing sequence errors is treated as an invalid image. The APNGloader will not attempt to repair and reorder files containing sequence errors.

Saving

When calling save(), by default only a single frame PNG filewill be saved. To save an APNG file (including a single frame APNG), the save_allparameter must be set to True. The following parameters can also be set:

  • default_image
  • Boolean value, specifying whether or not the base image is a default image.If True, the base image will be used as the default image, and the first imagefrom the append_images sequence will be the first APNG animation frame.If False, the base image will be used as the first APNG animation frame.Defaults to False.
  • append_images
  • A list or tuple of images to append as additional frames. Each of theimages in the list can be single or multiframe images. The size of each frameshould match the size of the base image. Also note that if a frame’s mode doesnot match that of the base image, the frame will be converted to the base imagemode.
  • loop
  • Integer number of times to loop this APNG, 0 indicates infinite looping.Defaults to 0.
  • duration
  • Integer (or list or tuple of integers) length of time to display this APNG frame(in milliseconds).Defaults to 0.
  • disposal

  • An integer (or list or tuple of integers) specifying the APNG disposaloperation to be used for this frame before rendering the next frame.Defaults to 0.

    • 0 (APNG_DISPOSE_OP_NONE, default) -No disposal is done on this frame before rendering the next frame.
    • 1 (PIL.PngImagePlugin.APNG_DISPOSE_OP_BACKGROUND) -This frame’s modified region is cleared to fully transparent black beforerendering the next frame.
    • 2 (APNG_DISPOSE_OP_PREVIOUS) -This frame’s modified region is reverted to the previous frame’s contents beforerendering the next frame.
  • blend

  • An integer (or list or tuple of integers) specifying the APNG blendoperation to be used for this frame before rendering the next frame.Defaults to 0.

    • 0 (APNG_BLEND_OP_SOURCE) -All color components of this frame, including alpha, overwrite the previous outputimage contents.
    • 1 (APNG_BLEND_OP_OVER) -This frame should be alpha composited with the previous output image contents.

Note

The duration, disposal and blend parameters can be set to lists or tuples tospecify values for each individual frame in the animation. The length of the list or tuplemust be identical to the total number of actual frames in the APNG animation.If the APNG contains a default image (i.e. default_image is set to True),these list or tuple parameters should not include an entry for the default image.

PPM

Pillow reads and writes PBM, PGM, PPM and PNM files containing 1, L orRGB data.

SGI

Pillow reads and writes uncompressed L, RGB, and RGBA files.

SPIDER

Pillow reads and writes SPIDER image files of 32-bit floating point data(“F;32F”).

Pillow also reads SPIDER stack files containing sequences of SPIDER images. Theseek() and tell() methods are supported, andrandom access is allowed.

The open() method sets the following attributes:

  • format
  • Set to SPIDER
  • istack
  • Set to 1 if the file is an image stack, else 0.
  • n_frames
  • Set to the number of images in the stack.

A convenience method, convert2byte(), is provided forconverting floating point data to byte data (mode L):

  1. im = Image.open('image001.spi').convert2byte()

Writing files in SPIDER format

The extension of SPIDER files may be any 3 alphanumeric characters. Thereforethe output format must be specified explicitly:

  1. im.save('newimage.spi', format='SPIDER')

For more information about the SPIDER image processing package, see theSPIDER homepage at Wadsworth Center.

TGA

Pillow reads and writes TGA images containing L, LA, P,RGB, and RGBA data. Pillow can read and write both uncompressed andrun-length encoded TGAs.

TIFF

Pillow reads and writes TIFF files. It can read both striped and tiledimages, pixel and plane interleaved multi-band images. If you havelibtiff and its headers installed, Pillow can read and write many kindsof compressed TIFF files. If not, Pillow will only read and writeuncompressed files.

Note

Beginning in version 5.0.0, Pillow requires libtiff to read orwrite compressed files. Prior to that release, Pillow had buggysupport for reading Packbits, LZW and JPEG compressed TIFFswithout using libtiff.

The open() method sets the followinginfo properties:

  • compression
  • Compression mode.

New in version 2.0.0.

  • dpi
  • Image resolution as an (xdpi, ydpi) tuple, where applicable. You can usethe tag attribute to get more detailedinformation about the image resolution.

New in version 1.1.5.

  • resolution
  • Image resolution as an (xres, yres) tuple, where applicable. This is ameasurement in whichever unit is specified by the file.

New in version 1.1.5.

The tag_v2 attribute contains a dictionaryof TIFF metadata. The keys are numerical indexes fromTAGS_V2. Values are strings or numbers for singleitems, multiple values are returned in a tuple of values. Rationalnumbers are returned as a IFDRationalobject.



New in version 3.0.0.



For compatibility with legacy code, thetag attribute contains a dictionary ofdecoded TIFF fields as returned prior to version 3.0.0. Values arereturned as either strings or tuples of numeric values. Rationalnumbers are returned as a tuple of (numerator, denominator).



Deprecated since version 3.0.0.



Reading Multi-frame TIFF Images

The TIFF loader supports the seek() andtell() methods, taking and returning frame numberswithin the image file. You can combine these methods to seek to the next frame(im.seek(im.tell() + 1)). Frames are numbered from 0 to im.num_frames - 1,and can be accessed in any order.

im.seek() raises an EOFError if you try to seek after thelast frame.

Saving Tiff Images

The save() method can take the following keyword arguments:

  • save_all
  • If true, Pillow will save all frames of the image to a multiframe tiff document.

New in version 3.4.0.

  • append_images
  • A list of images to append as additional frames. Each of theimages in the list can be single or multiframe images. Note however, that forcorrect results, all the appended images should have the sameencoderinfo and encoderconfig properties.

New in version 4.2.0.

  • tiffinfo
  • A ImageFileDirectory_v2 object or dictobject containing tiff tags and values. The TIFF field type isautodetected for Numeric and string values, any other typesrequire using an ImageFileDirectory_v2object and setting the type intagtype withthe appropriate numerical value fromTiffTags.TYPES.

New in version 2.3.0.

Metadata values that are of the rational type should be passed inusing a IFDRational object.

New in version 3.1.0.

For compatibility with legacy code, aImageFileDirectory_v1 object maybe passed in this field. However, this is deprecated.

New in version 5.4.0.

Previous versions only supported some tags when writing usinglibtiff. The supported list is found inLIBTIFF_CORE.

New in version 6.1.0.

Added support for signed types (e.g. TIFF_SIGNED_LONG) and multiple values.Multiple values for a single tag must be toImageFileDirectory_v2 as a tuple andrequire a matching type intagtype tagtype.

  • compression
  • A string containing the desired compression method for thefile. (valid only with libtiff installed) Valid compressionmethods are: None, "tiff_ccitt", "group3","group4", "tiff_jpeg", "tiff_adobe_deflate","tiff_thunderscan", "tiff_deflate", "tiff_sgilog","tiff_sgilog24", "tiff_raw_16"
  • quality
  • The image quality for JPEG compression, on a scale from 0 (worst) to 100(best). The default is 75.

New in version 6.1.0.

These arguments to set the tiff header fields are an alternative tousing the general tags available through tiffinfo.

description

software

date_time

artist

  • copyright
  • Strings
  • resolution_unit
  • An integer. 1 for no unit, 2 for inches and 3 for centimeters.
  • resolution
  • Either an integer or a float, used for both the x and y resolution.
  • x_resolution
  • Either an integer or a float.
  • y_resolution
  • Either an integer or a float.
  • dpi
  • A tuple of (x_resolution, y_resolution), with inches as the resolutionunit. For consistency with other image formats, the x and y resolutionsof the dpi will be rounded to the nearest integer.

WebP

Pillow reads and writes WebP files. The specifics of Pillow’s capabilities withthis format are currently undocumented.

The save() method supports the following options:

  • lossless
  • If present and true, instructs the WebP writer to use lossless compression.
  • quality
  • Integer, 1-100, Defaults to 80. For lossy, 0 gives the smallestsize and 100 the largest. For lossless, this parameter is the amountof effort put into the compression: 0 is the fastest, but gives largerfiles compared to the slowest, but best, 100.
  • method
  • Quality/speed trade-off (0=fast, 6=slower-better). Defaults to 0.
  • icc_profile
  • The ICC Profile to include in the saved file. Only supported ifthe system WebP library was built with webpmux support.
  • exif
  • The exif data to include in the saved file. Only supported ifthe system WebP library was built with webpmux support.

Saving sequences

Note

Support for animated WebP files will only be enabled if the system WebPlibrary is v0.5.0 or later. You can check webp animation support atruntime by calling features.check("webp_anim").

When calling save() to write a WebP file, thefollowing options are available when the save_all argument is present andtrue.

  • append_images
  • A list of images to append as additional frames. Each of theimages in the list can be single or multiframe images.
  • duration
  • The display duration of each frame, in milliseconds. Pass a singleinteger for a constant duration, or a list or tuple to set theduration for each frame separately.
  • loop
  • Number of times to repeat the animation. Defaults to [0 = infinite].
  • background
  • Background color of the canvas, as an RGBA tuple with values inthe range of (0-255).
  • minimize_size
  • If true, minimize the output size (slow). Implicitly disableskey-frame insertion.
  • kmin, kmax
  • Minimum and maximum distance between consecutive key frames inthe output. The library may insert some key frames as neededto satisfy this criteria. Note that these conditions shouldhold: kmax > kmin and kmin >= kmax / 2 + 1. Also, if kmax <= 0,then key-frame insertion is disabled; and if kmax == 1, then allframes will be key-frames (kmin value does not matter for thesespecial cases).
  • allow_mixed
  • If true, use mixed compression mode; the encoder heuristicallychooses between lossy and lossless for each frame.

XBM

Pillow reads and writes X bitmap files (mode 1).

Read-only formats

BLP

BLP is the Blizzard Mipmap Format, a texture format used in World ofWarcraft. Pillow supports reading JPEG Compressed or raw BLP1images, and all types of BLP2 images.

CUR

CUR is used to store cursors on Windows. The CUR decoder reads the largestavailable cursor. Animated cursors are not supported.

DCX

DCX is a container file format for PCX files, defined by Intel. The DCX formatis commonly used in fax applications. The DCX decoder can read files containing1, L, P, or RGB data.

When the file is opened, only the first image is read. You can useseek() or ImageSequence to read other images.

DDS

DDS is a popular container texture format used in video games and nativelysupported by DirectX.Currently, uncompressed RGB data and DXT1, DXT3, and DXT5 pixel formats aresupported, and only in RGBA mode.

New in version 3.4.0: DXT3

FLI, FLC

Pillow reads Autodesk FLI and FLC animations.

The open() method sets the followinginfo properties:

  • duration
  • The delay (in milliseconds) between each frame.

FPX

Pillow reads Kodak FlashPix files. In the current version, only the highestresolution image is read from the file, and the viewing transform is not takeninto account.

Note

To enable full FlashPix support, you need to build and install the IJG JPEGlibrary before building the Python Imaging Library. See the distributionREADME for details.

FTEX

New in version 3.2.0.

The FTEX decoder reads textures used for 3D objects inIndependence War 2: Edge Of Chaos. The plugin reads a single textureper file, in the compressed and uncompressed formats.

GBR

The GBR decoder reads GIMP brush files, version 1 and 2.

The open() method sets the followinginfo properties:

  • comment
  • The brush name.
  • spacing
  • The spacing between the brushes, in pixels. Version 2 only.

GD

Pillow reads uncompressed GD2 files. Note that you must usePIL.GdImageFile.open() to read such a file.

The open() method sets the followinginfo properties:

  • transparency
  • Transparency color index. This key is omitted if the image is nottransparent.

IMT

Pillow reads Image Tools images containing L data.

IPTC/NAA

Pillow provides limited read support for IPTC/NAA newsphoto files.

MCIDAS

Pillow identifies and reads 8-bit McIdas area files.

MIC

Pillow identifies and reads Microsoft Image Composer (MIC) files. When opened,the first sprite in the file is loaded. You can use seek() andtell() to read other sprites from the file.

Note that there may be an embedded gamma of 2.2 in MIC files.

MPO

Pillow identifies and reads Multi Picture Object (MPO) files, loading the primaryimage when first opened. The seek() and tell()methods may be used to read other pictures from the file. The pictures arezero-indexed and random access is supported.

PCD

Pillow reads PhotoCD files containing RGB data. This only reads the 768x512resolution image from the file. Higher resolutions are encoded in a proprietaryencoding.

PIXAR

Pillow provides limited support for PIXAR raster files. The library canidentify and read “dumped” RGB files.

The format code is PIXAR.

PSD

Pillow identifies and reads PSD files written by Adobe Photoshop 2.5 and 3.0.

WAL

New in version 1.1.4.

Pillow reads Quake2 WAL texture files.

Note that this file format cannot be automatically identified, so you must usethe open function in the WalImageFile module to read files inthis format.

By default, a Quake2 standard palette is attached to the texture. To overridethe palette, use the putpalette method.

WMF

Pillow can identify WMF files.

On Windows, it can read WMF files. By default, it will load the image at 72dpi. To load it at another resolution:

  1. from PIL import Image
  2. with Image.open("drawing.wmf") as im:
  3.     im.load(dpi=144)

To add other read or write support, usePIL.WmfImagePlugin.register_handler() to register a WMF handler.

  1. from PIL import Image
  2. from PIL import WmfImagePlugin
  3.  
  4. class WmfHandler:
  5.     def open(self, im):
  6.         ...
  7.     def load(self, im):
  8.         ...
  9.         return image
  10.     def save(self, im, fp, filename):
  11.         ...
  12.  
  13. wmf_handler = WmfHandler()
  14.  
  15. WmfImagePlugin.register_handler(wmf_handler)
  16.  
  17. im = Image.open("sample.wmf")

XPM

Pillow reads X pixmap files (mode P) with 256 colors or less.

The open() method sets the followinginfo properties:

  • transparency
  • Transparency color index. This key is omitted if the image is nottransparent.

Write-only formats

PALM

Pillow provides write-only support for PALM pixmap files.

The format code is Palm, the extension is .palm.

PDF

Pillow can write PDF (Acrobat) images. Such images are written as binary PDF 1.4files, using either JPEG or HEX encoding depending on the image mode (andwhether JPEG support is available or not).

The save() method can take the following keyword arguments:

  • save_all
  • If a multiframe image is used, by default, only the first image will be saved.To save all frames, each frame to a separate page of the PDF, the save_allparameter must be present and set to True.

New in version 3.0.0.

  • append_images
  • A list of images to append as additional pages. Each of theimages in the list can be single or multiframe images.

New in version 4.2.0.

  • append
  • Set to True to append pages to an existing PDF file. If the file doesn’texist, an IOError will be raised.

New in version 5.1.0.

  • resolution
  • Image resolution in DPI. This, together with the number of pixels in theimage, will determine the physical dimensions of the page that will besaved in the PDF.
  • title
  • The document’s title. If not appending to an existing PDF file, this willdefault to the filename.

New in version 5.1.0.

  • author
  • The name of the person who created the document.

New in version 5.1.0.

  • subject
  • The subject of the document.

New in version 5.1.0.

  • keywords
  • Keywords associated with the document.

New in version 5.1.0.

  • creator
  • If the document was converted to PDF from another format, the name of theconforming product that created the original document from which it wasconverted.

New in version 5.1.0.

  • producer
  • If the document was converted to PDF from another format, the name of theconforming product that converted it to PDF.

New in version 5.1.0.

  • creationDate
  • The creation date of the document. If not appending to an existing PDFfile, this will default to the current time.

New in version 5.3.0.

  • modDate
  • The modification date of the document. If not appending to an existing PDFfile, this will default to the current time.

New in version 5.3.0.

XV Thumbnails

Pillow can read XV thumbnail files.

Identify-only formats

BUFR

New in version 1.1.3.

Pillow provides a stub driver for BUFR files.

To add read or write support to your application, usePIL.BufrStubImagePlugin.register_handler().

FITS

New in version 1.1.5.

Pillow provides a stub driver for FITS files.

To add read or write support to your application, usePIL.FitsStubImagePlugin.register_handler().

GRIB

New in version 1.1.5.

Pillow provides a stub driver for GRIB files.

The driver requires the file to start with a GRIB header. If you have fileswith embedded GRIB data, or files with multiple GRIB fields, your applicationhas to seek to the header before passing the file handle to Pillow.

To add read or write support to your application, usePIL.GribStubImagePlugin.register_handler().

HDF5

New in version 1.1.5.

Pillow provides a stub driver for HDF5 files.

To add read or write support to your application, usePIL.Hdf5StubImagePlugin.register_handler().

MPEG

Pillow identifies MPEG files.