Install & Compatibility
Where this runs
tested against v2025.5.10 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
89MB installed
● package 89MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
imread
✓ from tifffile import imread
✗ import tifffile; image_data = tifffile.imread('image.tif')
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}'.")
Debug
Known issues
breakingThe `TiffPages.pages` and `FileSequence.files` attributes, as well as `stripnull`, `stripascii`, and `bytestr` functions, have been removed. Command-line interfaces were rewritten.fixMigrate 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].
affects: >=2026.0.0
breakingThe `TiffWriter.save` method is deprecated; use `TiffWriter.write` instead. Various other `TiffWriter` parameters like `compress` have been replaced by a `compression` parameter.fixUpdate `TiffWriter` calls to use `TiffWriter.write` and the `compression` keyword argument. For example, `tif.save(data, compress=6)` becomes `tif.write(data, compression=6)`.
affects: Check versions after 2021.3.31 for deprecation and removal [9].
breakingThe `multifile` parameter for `TiffFile` was removed. Support for Python 3.7 and earlier has been dropped, and Python 32-bit versions are deprecated.fixEnsure your environment uses Python 3.8+ (64-bit recommended). Review usage of `TiffFile` to remove the `multifile` parameter if present [9, 13].
affects: >=2021.3.31
gotchaFor very large TIFF files, loading the entire image into memory with `imread` can lead to `MemoryError`. Also, `TiffFile` objects should be properly closed.fixUse `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].
affects: All versions
gotchaSome 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.fixBe 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].
affects: All versions
breakingDecoding EER super-resolution sub-pixels and parsing EER metadata to dict changed significantly, introducing breaking changes.fixIf 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].
affects: >=2026.3.3
gotchaWhen 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.fixEnsure 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`.
affects: All versions
Upgrade
Version history
2026.8.23latest on PyPI · released Aug 23, 2026
Audit
Dependencies
numpyrequiredFundamental for array operations and image data handling.
imagecodecsoptionalProvides support for various compression and prediction schemes like LZW, JPEG, Zstd, and more.
matplotliboptionalOptional for plotting functionality.