tifffile
Read and write TIFF files
Downloads: 0 (30 days)
Description
Read and write TIFF files
=========================
Tifffile is a comprehensive Python library to
(1) store NumPy arrays in TIFF (Tagged Image File Format) files, and
(2) read image and metadata from TIFF-like files used in bioimaging.
Image and metadata can be read from TIFF, BigTIFF, OME-TIFF, GeoTIFF,
Adobe DNG, ZIF (Zoomable Image File Format), MetaMorph STK, Zeiss LSM,
ImageJ hyperstack, Micro-Manager MMStack and NDTiff, SGI, NIHImage,
Olympus FluoView and SIS, ScanImage, Molecular Dynamics GEL,
Aperio SVS, Leica SCN, Roche BIF, PerkinElmer QPTIFF (QPI, PKI),
Hamamatsu NDPI, Argos AVS, Philips DP, and ThermoFisher EER formatted files.
Image data can be read as NumPy arrays or Zarr arrays/groups from strips,
tiles, pages (IFDs), SubIFDs, higher-order series, and pyramidal levels.
Image data can be written to TIFF, BigTIFF, OME-TIFF, and ImageJ hyperstack
compatible files in multi-page, volumetric, pyramidal, memory-mappable,
tiled, predicted, or compressed form.
Many compression and predictor schemes are supported via the imagecodecs
library, including LZW, PackBits, Deflate, PIXTIFF, LZMA, LERC, Zstd,
JPEG (8 and 12-bit, lossless), JPEG 2000, JPEG XR, JPEG XL, WebP, PNG, EER,
Jetraw, 24-bit floating-point, and horizontal differencing.
Tifffile can also be used to inspect TIFF structures, read image data from
multi-dimensional file sequences, write fsspec ReferenceFileSystem for
TIFF files and image file sequences, patch TIFF tag values, and parse
many proprietary metadata formats.
:Author: `Christoph Gohlke <https://www.cgohlke.com>`_
:License: BSD-3-Clause
:Version: 2026.2.24
:DOI: `10.5281/zenodo.6795860 <https://doi.org/10.5281/zenodo.6795860>`_
Quickstart
----------
Install the tifffile package and all dependencies from the
`Python Package Index <https://pypi.org/project/tifffile/>`_::
python -m pip install -U tifffile[all]
Tifffile is also available in other package repositories such as Anaconda,
Debian, and MSYS2.
The tifffile library is type annotated and documented via docstrings::
python -c "import tifffile; help(tifffile)"
Tifffile can be used as a console script to inspect and preview TIFF files::
python -m tifffile --help
See `Examples`_ for using the programming interface.
Source code and support are available on
`GitHub <https://github.com/cgohlke/tifffile>`_.
Support is also provided on the
`image.sc <https://forum.image.sc/tag/tifffile>`_ forum.
Requirements
------------
This revision was tested with the following requirements and dependencies
(other versions may work):
- `CPython <https://www.python.org>`_ 3.11.9, 3.12.10, 3.13.12, 3.14.3 64-bit
- `NumPy <https://pypi.org/project/numpy>`_ 2.4.2
- `Imagecodecs <https://pypi.org/project/imagecodecs/>`_ 2026.1.14
(required for encoding or decoding LZW, JPEG, etc. compressed segments)
- `Matplotlib <https://pypi.org/project/matplotlib/>`_ 3.10.8
(required for plotting)
- `Lxml <https://pypi.org/project/lxml/>`_ 6.0.2
(required only for validating and printing XML)
- `Zarr <https://pypi.org/project/zarr/>`_ 3.1.5
(required only for using Zarr stores; Zarr 2 is not compatible)
- `Kerchunk <https://pypi.org/project/kerchunk/>`_ 0.2.9
(required only for opening ReferenceFileSystem files)
Revisions
---------
2026.2.24
- Pass 5132 tests.
- Remove deprecated TiffPages.pages and FileSequence.files (breaking).
- Remove stripnull, stripascii, and bytestr functions (breaking).
- Rewrite command line interfaces (breaking).
- Support Experimenter and Project elements in OmeXml.
- Refactor TiffPages.
- Fix code review issues.
2026.2.20
- Fix rounding of high resolutions (#318).
- Fix code review issues.
2026.2.16
- Optimize reading multi-file pyramidal OME TIFF files.
2026.2.15
- Support reading multi-file pyramidal OME TIFF files (image.sc/t/119259).
2026.1.28
- Deprecate colormaped parameter in imagej_description (use colormapped).
- Fix code review issues.
2026.1.14
- Improve code quality.
2025.12.20
- Do not initialize output arrays.
2025.12.12
- Improve code quality.
2025.10.16
- Add option to decode EER super-resolution sub-pixels (breaking, #313).
- Parse EER metadata to dict (breaking).
2025.10.4
- Fix parsing SVS description ending with "|".
2025.9.30
- Fix reading NDTiff series with unordered axes in index (#311).
2025.9.20
- Derive TiffFileError from ValueError.
- Natural-sort files in glob pattern passed to imread by default (breaking).
- Fix optional sorting of list of files passed to FileSequence and imread.
2025.9.9
- Consolidate Nuvu camera metadata.
2025.8.28
- Support DNG DCP files (#306).
2025.6.11
- Fix reading images with dimension length 1 through Zarr (#303).
2025.6.1
- Add experimental option to write iterator of bytes and bytecounts (#301).
2025.5.26
- Use threads in Zarr stores.
2025.5.24
- Fix incorrect tags created by Philips DP v1.1 (#299).
- Make Zarr stores partially listable.
2025.5.21
- Move Zarr stores to tifffile.zarr namespace (breaking).
- Require Zarr 3 for Zarr stores and remove support for Zarr 2 (breaking).
- Drop support for Python 3.10.
2025.5.10
- Raise ValueError when using Zarr 3 (#296).
- Fall back to compression.zstd on Python >= 3.14 if no imagecodecs.
- Remove doctest command line option.
- Support Python 3.14.
2025.3.30
- Fix for imagecodecs 2025.3.30.
2025.3.13
- …
Refer to the CHANGES file for older revisions.
Notes
-----
TIFF, the Tagged Image File Format, was created by the Aldus Corporation and
Adobe Systems Incorporated.
Tifffile supports a subset of the TIFF6 specification, mainly 8, 16, 32, and
64-bit integer, 16, 32, and 64-bit float, grayscale and multi-sample images.
Specifically, CCITT and OJPEG compression, chroma subsampling without JPEG
compression, color space transformations, samples with differing types, or
IPTC, ICC, and XMP metadata are not implemented.
Besides classic TIFF, tifffile supports several TIFF-like formats that do not
strictly adhere to the TIFF6 specification. Some formats extend TIFF
capabilities in various ways, including exceeding the 4 GB limit,
handling multi-dimensional data, or working around format constraints:
- **BigTIFF** is identified by version number 43 and uses different file
header, IFD, and tag structures with 64-bit offsets. The format also adds
64-bit data types. Tifffile can read and write BigTIFF files.
- **ImageJ hyperstacks** store all image data, which may exceed 4 GB,
contiguously after the first IFD. Files > 4 GB contain one IFD only.
The size and shape of the up to 6-dimensional image data can be determined
from the ImageDescription tag of the first IFD, which is Latin-1 encoded.
Tifffile can read and write ImageJ hyperstacks.
- **OME-TIFF** files store up to 8-dimensional image data in one or multiple
TIFF or BigTIFF files. The UTF-8 encoded OME-XML metadata found in the
ImageDescription tag of the first IFD defines the position of TIFF IFDs in
the high-dimensional image data. Tifffile can read OME-TIFF files
and write NumPy arrays to single-file OME-TIFF.
- **Micro-Manager NDTiff** stores multi-dimensional image data in one
or more classic TIFF files. Metadata contained in a separate NDTiff.index
binary file defines the position of the TIFF IFDs in the image array.
Each TIFF file also contains metadata in a non-TIFF binary structure at
offset 8. Downsampled image data of pyramidal datasets are stored in
separate folders. Tifffile can read NDTiff files. Version 0 and 1 series,
tiling, stitching, and multi-resolution pyramids are not supported.
- **Micro-Manager MMStack** stores 6-dimensional image data in one or more
classic TIFF files. Metadata contained in non-TIFF binary structures and
JSON strings define the image stack dimensions and the position of the image
frame data in the file and the image stack. The TIFF structures and metadata
are often corrupted or wrong. Tifffile can read MMStack files.
- **Carl Zeiss LSM** files store all IFDs below 4 GB and wrap around 32-bit
StripOffsets pointing to image data above 4 GB. The StripOffsets of each
series and position require separate unwrapping. The StripByteCounts tag
contains the number of bytes for the uncompressed data. Tifffile can read
LSM files of any size.
- **MetaMorph STK** files contain additional image planes stored
contiguously after the image data of the first page. The total number of
planes is equal to the count of the UIC2 tag. Tifffile can read STK files.
- **ZIF**, the Zoomable Image File format, is a subspecification of BigTIFF
with SGI's ImageDepth extension and additional compression schemes.
Only little-endian, tiled, interleaved, 8-bit per sample images with
JPEG, PNG, JPEG XR, and JPEG 2000 compression are allowed. Tifffile can
read and write ZIF files.
- **Hamamatsu NDPI** files use some 64-bit offsets in the file header, IFD,
and tag structures. Single, LONG typed tag values can exceed 32-bit.
The high bytes of 64-bit tag values and offsets are stored after IFD
structures. Tifffile can read NDPI files > 4 GB.
JPEG compressed segments with dimensions >65530 or missing restart markers
cannot be decoded with common JPEG libraries. Tifffile works around this
limitation by separately decoding the MCUs between restart markers, which
performs poorly. BitsPerSample, SamplesPerPixel, and
PhotometricInterpretation tags may contain wrong values, which can be
corrected using the value of tag 65441.
- **Philips TIFF** slides store padded ImageWidth and ImageLength tag values
for tiled pages. The values can be corrected using the DICOM_PIXEL_SPACING
attributes of the XML formatted description of the first page. Tile offsets
and byte counts may be 0. T