Tifffile: Read and Write TIFF Files

raw JSON →
2026.3.3 verified Tue May 12 auth: no python install: stale

Tifffile is a Python library designed for reading and writing TIFF files, particularly those prevalent in scientific imaging. It offers extensive support for various TIFF formats, including BigTIFF, OME-TIFF, and multi-page TIFF stacks. Actively maintained, it receives frequent updates, with the current version being 2026.3.3, reflecting continuous development and improvements.

pip install tifffile
error ModuleNotFoundError: No module named 'tifffile'
cause The 'tifffile' package is not installed in your current Python environment.
fix
pip install tifffile
error ValueError: unknown compression tag
cause The TIFF file uses a compression method that tifffile cannot decode because the necessary optional dependency, 'imagecodecs', is not installed, or the specific codec is not supported by 'imagecodecs'.
fix
pip install imagecodecs
error TypeError: 'TiffFile' object is not subscriptable
cause You are attempting to access individual image pages directly on the 'TiffFile' object using list-like indexing (e.g., tif[0]), which is not supported.
fix
Access image data using .asarray() for the entire stack or .pages[index].asarray() for specific pages within the file object: with tifffile.TiffFile('file.tif') as tif: image_data = tif.pages[0].asarray()
error AttributeError: 'numpy.ndarray' object has no attribute 'pages'
cause You are trying to access the 'pages' attribute on a NumPy array that has already been loaded from a TIFF file using `tifffile.imread()`, rather than on the 'TiffFile' object itself.
fix
If you need to access individual pages or metadata, open the file using with tifffile.TiffFile(filename) as tif: and then access tif.pages[index]. If you only need the array data, tifffile.imread(filename) is sufficient.
breaking The `TiffPages.pages` and `FileSequence.files` attributes, as well as `stripnull`, `stripascii`, and `bytestr` functions, have been removed. Command-line interfaces were rewritten.
fix Migrate code to use current API for page and file sequence access. Consult the `tifffile` GitHub repository for specific replacements in the releases or changes log [6].
breaking The `TiffWriter.save` method is deprecated; use `TiffWriter.write` instead. Various other `TiffWriter` parameters like `compress` have been replaced by a `compression` parameter.
fix Update `TiffWriter` calls to use `TiffWriter.write` and the `compression` keyword argument. For example, `tif.save(data, compress=6)` becomes `tif.write(data, compression=6)`.
breaking The `multifile` parameter for `TiffFile` was removed. Support for Python 3.7 and earlier has been dropped, and Python 32-bit versions are deprecated.
fix Ensure your environment uses Python 3.8+ (64-bit recommended). Review usage of `TiffFile` to remove the `multifile` parameter if present [9, 13].
gotcha For very large TIFF files, loading the entire image into memory with `imread` can lead to `MemoryError`. Also, `TiffFile` objects should be properly closed.
fix Use `tifffile.memmap` for memory-efficient access to large files, or iterate through `TiffFile` pages to process chunks. Always use `TiffFile` within a `with` statement to ensure it is properly closed [3, 14].
gotcha Some TIFF-like formats do not strictly adhere to the TIFF6 specification, which might lead to unexpected behavior or incomplete data reading if not handled correctly.
fix Be aware that `tifffile` supports a large subset but not all possible TIFF variations. Consult the documentation for specific format support, especially for proprietary formats [1, 4].
breaking Decoding EER super-resolution sub-pixels and parsing EER metadata to dict changed significantly, introducing breaking changes.
fix If working with EER files, review code that decodes EER sub-pixels or parses EER metadata, as the API has changed. Refer to the latest documentation or release notes for the new approach [4, 6].
gotcha When installing `tifffile` in minimal environments (like Alpine Linux), compilation of C extensions for optional dependencies such as `imagecodecs` and `numcodecs` may fail due to missing system build tools (e.g., `gcc`). This can lead to reduced functionality, as many compression and codec options provided by these dependencies will be unavailable.
fix Ensure that the necessary build tools are installed in your environment before attempting to install `tifffile`. For Alpine Linux, this typically involves running `apk add build-base python3-dev`.
pip install -U tifffile[all]
conda install tifffile -c conda-forge
python os / libc variant status wheel install import disk
3.10 alpine (musl) -U build_error - - - -
3.10 alpine (musl) -U - - - -
3.10 alpine (musl) tifffile wheel - - 91.0M
3.10 alpine (musl) tifffile - - - -
3.10 slim (glibc) -U sdist 11.2s - 354M
3.10 slim (glibc) -U - - - -
3.10 slim (glibc) tifffile wheel 3.7s - 87M
3.10 slim (glibc) tifffile - - - -
3.11 alpine (musl) -U build_error - - - -
3.11 alpine (musl) -U - - - -
3.11 alpine (musl) tifffile wheel - - 99.0M
3.11 alpine (musl) tifffile - - - -
3.11 slim (glibc) -U wheel 10.3s - 321M
3.11 slim (glibc) -U - - - -
3.11 slim (glibc) tifffile wheel 3.7s - 95M
3.11 slim (glibc) tifffile - - - -
3.12 alpine (musl) -U build_error - - - -
3.12 alpine (musl) -U - - - -
3.12 alpine (musl) tifffile wheel - - 87.6M
3.12 alpine (musl) tifffile - - - -
3.12 slim (glibc) -U wheel 14.2s - 400M
3.12 slim (glibc) -U - - - -
3.12 slim (glibc) tifffile wheel 3.7s - 83M
3.12 slim (glibc) tifffile - - - -
3.13 alpine (musl) -U build_error - - - -
3.13 alpine (musl) -U - - - -
3.13 alpine (musl) tifffile wheel - - 87.1M
3.13 alpine (musl) tifffile - - - -
3.13 slim (glibc) -U wheel 14.1s - 399M
3.13 slim (glibc) -U - - - -
3.13 slim (glibc) tifffile wheel 3.6s - 83M
3.13 slim (glibc) tifffile - - - -
3.9 alpine (musl) -U build_error - - - -
3.9 alpine (musl) -U - - - -
3.9 alpine (musl) tifffile wheel - - 98.8M
3.9 alpine (musl) tifffile - - - -
3.9 slim (glibc) -U sdist 12.8s - 356M
3.9 slim (glibc) -U - - - -
3.9 slim (glibc) tifffile wheel 4.4s - 97M
3.9 slim (glibc) tifffile - - - -

This quickstart demonstrates how to write a NumPy array to a TIFF file, read it back, verify its content, and access basic metadata using `tifffile.imwrite`, `tifffile.imread`, and the `tifffile.TiffFile` context manager. It also includes cleanup of the created file.

import numpy as np
import tifffile
import os

# Create some dummy image data
dummy_image = np.random.rand(100, 100).astype(np.float32)

# Define a filename
filename = 'example.tif'

# Write the image data to a TIFF file
tifffile.imwrite(filename, dummy_image, description='Generated by tifffile quickstart')
print(f"Successfully wrote '{filename}'")

# Read the image data back from the TIFF file
read_image = tifffile.imread(filename)
print(f"Successfully read '{filename}' with shape: {read_image.shape}")

# Verify data
assert np.array_equal(dummy_image, read_image)
print("Original and read image data are identical.")

# Access metadata using TiffFile context manager
with tifffile.TiffFile(filename) as tif:
    if tif.pages:
        first_page_description = tif.pages[0].tags.get('ImageDescription')
        if first_page_description:
            print(f"ImageDescription from file: {first_page_description.value}")
        else:
            print("No ImageDescription found for the first page.")
    else:
        print("No pages found in the TIFF file.")

# Clean up the created file
os.remove(filename)
print(f"Cleaned up '{filename}'.")