Quickstart

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

python -m pip install -U liffile[all]

View image and metadata stored in a LIF file:

python -m liffile file.lif

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.0rc 64-bit

• Numpy 2.5.3

• Imagecodecs 2026.8.16 (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.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

• 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

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