mzx

Free and open conversion of mass spec data

What it does

mzx wraps msconvert from ProteoWizard inside Docker so you can convert vendor raw formats to open formats (mzML, MGF, mzXML, …) from the command line or an optional GUI.

Prerequisites

• Docker — installed and running (the CLI calls docker run to execute msconvert).
• Python 3.10+
• pip, uv, or another PEP 517–compatible installer

Install

pip install -U mzx

Quick start

1. Ensure Docker is running (docker info should succeed).

2. Convert a Thermo .raw file to mzML (default output format):

   mzx /path/to/data.raw

   The mzML is written next to the input file (same directory, .mzML extension).

3. To choose another output format, set --type to mzml, mgf, or mzxml:

   mzx --type mgf /path/to/data.raw

See mzx --help for peak picking, indexing, Waters lockmass options, and more.

GUI (experimental)

After install, start the GUI:

mzx-gui

If the mzx-gui command is not on your PATH (common on Windows), use either:

python -m mzx.gui

or the Python Launcher for Windows:

py -m mzx.gui

The CLI can always be run as python -m mzx (same as the mzx command).

Vendor support

Conversion uses ProteoWizard; supported vendors include Agilent, Bruker, Sciex, Shimadzu, Thermo, Waters, and UIMF. See the ProteoWizard FAQ for vendor-specific notes.

Supported file formats (examples)

• .mgf
• .mzML
• .raw (Thermo)
• .wiff (Sciex)

Features

• Convert between common mass spectrometry interchange formats via msconvert
• Vendor formats: Agilent, Bruker, Sciex, Thermo, Waters, and others supported by ProteoWizard
• CLI and experimental GUI

Documentation

Full documentation: mzx.readthedocs.io

Development

From a clone of the repo, using uv (recommended):

make setup
source .venv/bin/activate   # Windows: .venv\Scripts\activate
make install

make setup creates .venv and installs development dependencies from requirements.txt. make install installs mzx in editable mode.

Without make, the same steps are:

uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
uv pip install -e .

Run tests:

make test

Other useful targets: make lint, make help.

License

GNU General Public License v3 — see LICENSE.