liffile 2026.7.14

Quickstart

Install the liffile package and all dependencies from the Python Package Index:

python -m pip install -U liffile[all]

See Examples for using the programming interface.

Source code and support are available on GitHub.

Requirements

This revision was tested with the following requirements and dependencies (other versions may work):

• CPython 3.12.10, 3.13.14, 3.14.6, 3.15.0b3 64-bit

• NumPy 2.5.1

• Imagecodecs 2026.6.26 (required for decoding TIFF, JPEG, PNG, and BMP)

• Tifffile 2026.7.14 (required for reading multi-page TIFF)

• Xarray 2026.7.0 (recommended)

• Matplotlib 3.11.0 (optional)

Revisions

2026.7.14

• Add option to memory-map LIF files.

• Drop support for numpy 2.0 (SPEC0).

• Support Python 3.15.

2026.4.11

• Add channel name resolution to LifImage via coords[‘C’] and coords[‘S’].

• Drop support for Python 3.11.

2026.2.16

• Change timestamps to None if not present (breaking).

• Fix inefficient timestamp parsing.

• Fix inefficient LifFile.close().

• Add tilescan property to LifImage.

2026.2.15

• Add experimental frame-based interface to LifImage.

• Fix code review issues.

2026.1.22

• Fix reading sequence of LifMemoryBlocks.

• Change unknown axis code to ‘?’.

2026.1.14

• Improve code quality.

2025.12.12

• Remove deprecated LifFile.series and xml_element_smd properties (breaking).

• Improve code quality.

2025.11.8

• Add option to find other LifImageSeries attributes than path.

• Return UniqueID in LifImage.attrs.

• Factor out BinaryFile base class.

2025.9.28

• Derive LifFileError from ValueError.

• Minor fixes.

• Drop support for Python 3.10.

2025.5.10

• …

Refer to the CHANGES file for older revisions.

Notes

The API is not stable yet and might change between revisions.

Leica Microsystems GmbH is a manufacturer of microscopes and scientific instruments. Leica image files are proprietary formats written by Leica acquisition software such as LAS X and LAS AF to store microscopy images and metadata.

The Leica Image File (LIF) begins with a magic number followed by a UTF-16 XML header that describes images and metadata, then stores the raw pixel data for each image in contiguous data blocks. Images may be multi-dimensional (X, Y, Z, T, C, …) with multiple channels, and a single file can contain many independent image series. Related formats include LOF (single-object variant), XLIF, XLEF, and XLCF (XML-based containers), XLLF (folder-view), and LIFEXT (optional image data extensions).

This library is not feature-complete. Unsupported features currently include XLLF, image mosaics and pyramids, bit increments, and non-image data such as raw FLIM/TCSPC histogram data.

The library has been tested with only a limited number of version 2 files.

The Leica image file formats are documented in:

• Leica Image File Formats - LIF, XLEF, XLLF, LOF. Version 3.2. Leica Microsystems GmbH. 21 September 2016.

• Annotations to Leica Image File Formats for LAS X Version 3.x. Version 1.4. Leica Microsystems GmbH. 24 August 2016.

• TSC SP8 FALCON File Format Description. LAS X Version 3.5.0.

Other implementations for reading Leica image files are readlif and Bio-Formats.

Examples

Read a FLIM lifetime image and metadata from a LIF file:

>>> with LifFile('tests/data/FLIM.lif') as lif:
...     for image in lif.images:
...         _ = image.name
...     image = lif.images['Fast Flim']  # by name
...     assert image.dtype == 'float16'
...     assert image.sizes == {'Y': 1024, 'X': 1024}
...     lifetimes = image.asxarray()
...
>>> lifetimes
<xarray.DataArray 'Fast Flim' (Y: 1024, X: 1024)> Size: 2MB
array([[...]],
      shape=(1024, 1024), dtype=float16)
Coordinates:
  * Y        (Y) float64... 0.0005564
  * X        (X) float64... 0.0005564
Attributes...
    path:           FLIM_testdata.lif/sample1_slice1/FLIM Compressed/Fast Flim
    UniqueID:       694efd02-95a9-436e-0fa6-f146120b1e15
    F16:            {'Name': 'F16',...
    TileScanInfo:   {'Tile': {'FieldX': 0,...
    ViewerScaling:  {'ChannelScalingInfo': {...

Iterate over selected XLEF image frames in ZTM dimension order:

>>> with LifFile('tests/data/XYZCST/XYZCST.xlef') as lif:
...     image = lif.images[0]  # by index
...     image.sizes
...     frames = image.frames(C=1, Z=slice(1, 3), T=[1, 0], M=None)
...     frames.sizes
...     for index, frame in frames.items():
...         index, frame.shape
...
{'T': 2, 'M': 4, 'C': 3, 'Z': 5, 'Y': 1200, 'X': 1600}
{'Z': 2, 'T': 2, 'M': 4, 'Y': 1200, 'X': 1600}
((0, 0, 0), (1200, 1600))
((0, 0, 1), (1200, 1600))
...
((1, 1, 2), (1200, 1600))
((1, 1, 3), (1200, 1600))

View image and metadata in a LIF file from the console:

$ python -m liffile tests/data/FLIM.lif