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 Common errors
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. Warnings
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`.
Install
pip install -U tifffile[all] conda install tifffile -c conda-forge Install compatibility stale last tested: 2026-05-12
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 - - - -
Imports
- imread
import tifffile; image_data = tifffile.imread('image.tif') - imwrite
import tifffile; tifffile.imwrite('output.tif', image_data) - TiffFile
from tifffile import TiffFile; with TiffFile('image.tif') as tif: ...
Quickstart last tested: 2026-04-24
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}'.")