Quickstart

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

python -m pip install -U liffile[all]

See Examples and Documentation 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.16, 3.14.8, 3.15.0 64-bit

• Numpy 2.5.4

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

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

• Xarray 2026.9.0 (recommended)

• Matplotlib 3.11.2 (optional)

Revisions

2026.10.14

• Fix child files not closed when LifFile is opened from binary stream.

• Fix zero-length frame selections squeezed like singleton dimensions.

• Fix missing index validation for frames in XLIF referencing OME/AIVIA TIFF.

2026.10.8

• Support XLLF (folder view) files.

2026.10.3

• Do not remove images with duplicate paths (bioio-lif issue 55).

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

• …

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 image mosaics and pyramids, bit increments, heterogeneous channel dtypes, and non-image data such asraw 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

Import functions and classes used in these examples:

>>> from liffile import LifFile

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