mzmlpy 0.9.2

mzmlpy is a Python library for reading mzML mass spectrometry files. It's built for people writing proteomics or metabolomics pipelines who need a reader that's fast on large files, tells them exactly what's wrong with a malformed file, and doesn't force a full decode just to look at a spectrum's metadata.

Why mzmlpy?

• Lazy by design — metadata is parsed up front; binary m/z and intensity arrays are only decoded when you actually touch them.
• Fast — 5–9x faster than pymzml on complex files in our benchmarks (see below).
• Type-safe — dataclass-based models with full type annotations, not loosely-typed XML trees.
• Handles gzip well — reads .mzML.gz directly, with a self-indexed gzip format for random access without re-extracting the file.
• Common compressions — zlib out of the box; zstd and MS-Numpress through optional extras.
• Validates, not just parses — a validate() function reports structural and decoding problems instead of silently producing bad data.

Install

pip install mzmlpy

Optional extras:

pip install mzmlpy[numpress]   # MS-Numpress decoding
pip install mzmlpy[zstd]       # Zstandard compression
pip install mzmlpy[rapidgzip]  # Parallel gzip decompression (recommended for .gz files)
pip install mzmlpy[mcp]        # MCP server for AI coding assistants

Quick example

from mzmlpy import Mzml

with Mzml("path/to/file.mzML") as reader:
    print(f"File: {reader.file_name}  |  Spectra: {len(reader.spectra)}")

    for spectrum in reader.spectra:
        mz = spectrum.mz
        intensity = spectrum.intensity
        print(f"  {spectrum.id} MS{spectrum.ms_level} — {len(mz)} peaks")

Both .mzML and .mzML.gz files are supported. Metadata is parsed eagerly; binary data is decoded on demand.

What else it can do

from mzmlpy import Mzml, validate

# Structural/decoding validation, no repair attempted
report = validate("data.mzML", decode_binary=True)
print(report.valid, report.issues)

# Filter by metadata without decoding any arrays
with Mzml("data.mzML", in_memory=False) as reader:
    for spectrum in reader.spectra.filter(ms_level=2, retention_time=(60, 180)):
        print(spectrum.id)

Gzipped files get the same lazy, indexable access as plain mzML — gzip_mode picks between an embedded index, an extracted cache, or streaming, and self-indexed files (via write_indexed_gzip) support random access with no extraction step at all. Ion mobility data (e.g. Bruker timsTOF PASEF) is exposed on the spectrum whether it's stored as a binary array or a scan-level parameter.

See the Getting Started guide and API Reference for the full picture, including gzip mode details, the CLI, and the MCP server.

Using an AI coding assistant? Point it at llms.txt, a short index of the package and its docs, or at llms-full.txt for the full API guide with signatures and examples.

In the tacular-omics family

mzmlpy reads mzML; tdfpy reads the Bruker timsTOF .d format the same way. Both feed spectra into spxtacular, the shared spectrum-processing layer for deisotoping, deconvolution, and downstream analysis.

Links

• Docs: https://tacular-omics.github.io/mzmlpy/
• Changelog: CHANGELOG.md

Citation

Citation metadata are provided in CITATION.cff. All archived releases are available from Zenodo at doi:10.5281/zenodo.21960079.

Benchmarks

benchmarks/ contains a reproducible harness comparing mzmlpy against pyteomics and pymzml on compression-format support, throughput, and gzip handling.

Compared against pymzml 2.6.0 on a Bruker timsTOF file with ion mobility (10 spectra, 6.7 MB):

Both libraries produce identical m/z and intensity arrays. The gap narrows on smaller files (~1.1–1.3x) and widens on larger, more complex files. See benchmarks/README.md for how to run it yourself, and the full results on the Benchmarks page.

License

MIT — see LICENSE.