Common Causes of pyOpenMS Installation Failures: A Troubleshooting Guide

pyOpenMS installation failures typically stem from missing C++ build toolchains, incompatible Python versions (3.8–3.11 required), absent system libraries like Qt5 and Boost, or insufficient resources to compile the underlying OpenMS C++ library.

The K-Dense-AI/scientific-agent-skills repository provides a modular collection of domain-specific capabilities, including the pyOpenMS skill located at scientific-skills/pyopenms/, which wraps the OpenMS C++ library via Python bindings. Because this skill depends on heavy compiled components and external C++ dependencies (Boost, Eigen, Qt), the installation process documented in SKILL.md often encounters environment-specific failures when the system lacks prerequisite build tools or compatible library versions.

Architecture of the pyOpenMS Skill

In the Scientific Agent Skills framework, each capability is declared as a skill with a YAML front-matter block and documented in a SKILL.md descriptor. The pyopenms skill exposes proteomics and metabolomics functionality through the pyopenms package, but unlike pure Python libraries, it requires the OpenMS C++ core to be present or compiled during installation. When no pre-compiled wheel exists for your platform, uv pip install pyopenms falls back to building from source, triggering failures if your environment lacks the necessary compilers or system libraries.

Common Causes of pyOpenMS Installation Failures

Missing C++ Build Toolchain

When wheels are unavailable, the installer attempts to compile OpenMS from source, which fails immediately if a C++ compiler is absent. On Linux and macOS, you need GCC ≥ 7 or Clang ≥ 6 along with CMake and development headers.

Install the required toolchain before attempting uv pip install pyopenms:

# Debian/Ubuntu

sudo apt-get install build-essential cmake libboost-all-dev

# macOS

brew install cmake boost eigen

Incompatible Python Version

pyOpenMS supports Python 3.8 through 3.11 only. Using Python 3.7 or 3.12 triggers a PEP 517 build error because the package metadata specifies these constraints, and the repository's skill files do not enforce version checks before installation.

Always verify your interpreter version matches the supported range:

python --version  # Should be 3.8, 3.9, 3.10, or 3.11

Missing System Libraries

Even when pre-compiled wheels are available, OpenMS depends on shared system libraries including Qt5, zlib, libpng, and libtiff. The SKILL.md descriptor lists only the Python package requirement, not these underlying C++ prerequisites. If these libraries are absent, the wheel will install but fail at runtime with ImportError or library loading errors.

On Debian-based systems, install the dependencies:

sudo apt-get install libqt5gui5 libqt5core5a libqt5svg5 libpng-dev libtiff5-dev zlib1g-dev

Conflicting Boost or Eigen Versions

Version conflicts in system-wide C++ libraries can cause compilation to fail or produce runtime crashes. OpenMS requires Boost ≥ 1.65 and Eigen ≥ 3.3, but if your system has multiple versions installed or outdated variants in the library path, the build system may link against the wrong libraries.

On macOS, use Homebrew to ensure compatible variants are present and properly linked:

brew install boost@1.76 eigen
export CMAKE_PREFIX_PATH=$(brew --prefix boost@1.76)

Resource Constraints During Compilation

Building from source is resource-intensive, requiring more than 2 GB of RAM and 5 GB of temporary disk space. On low-resource CI runners or small cloud instances, the compilation process will be killed by the OOM (Out of Memory) manager or run out of disk space during the intermediate object file generation.

If you cannot allocate sufficient resources, use a pre-built Docker image containing pyOpenMS instead of compiling locally.

Corrupted pip Cache

A partially downloaded or corrupted wheel stored in the pip cache can cause checksum failures on subsequent installation attempts. The repository's installation commands use uv pip install, which does not automatically clear stale cache entries.

Resolve this by purging the cache before reinstalling:

uv pip cache purge

# Or manually remove: rm -rf ~/.cache/pip

Network Restrictions and Proxies

Corporate firewalls may block the download of large binary wheels (approximately 150 MB) from PyPI. The skill's installation block does not include proxy handling, causing the download to timeout or fail with SSL errors.

Configure your environment to use the corporate proxy or download the wheel manually:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
uv pip install pyopenms

Alternatively, download the appropriate wheel from PyPI and install locally:

uv pip install ./pyopenms-*.whl

Verifying a Successful Installation

Once installation succeeds, verify functionality using patterns from the skill's reference modules. The following examples demonstrate core entry points used by downstream skills like statistical-analysis and visualization.

Loading Mass Spectrometry Data

import pyopenms as ms

exp = ms.MSExperiment()
ms.MzMLFile().load("data/sample.mzML", exp)

print(f"Spectra count: {exp.getNrSpectra()}")
first = exp.getSpectrum(0)
print(f"First spectrum – MS level: {first.getMSLevel()}, RT: {first.getRT():.2f}")
mz, intensity = first.get_peaks()
print(f"Peaks in first spectrum: {len(mz)}")

Signal Processing

gauss = ms.GaussFilter()
params = gauss.getParameters()
params.setValue("gaussian_width", 0.15)
gauss.setParameters(params)
gauss.filterExperiment(exp)

Feature Detection

ff = ms.FeatureFinder()
features = ms.FeatureMap()
ff.run("centroided", exp, features, ms.Param(), ms.FeatureMap())
print(f"Detected features: {features.size()}")

Peptide Identification with FDR Control

protein_ids, peptide_ids = [], []
ms.IdXMLFile().load("identifications.idXML", protein_ids, peptide_ids)

fdr = ms.FalseDiscoveryRate()
fdr.apply(peptide_ids)
print(f"Peptides after FDR: {len(peptide_ids)}")

Exporting to Pandas

import pandas as pd

fm = ms.FeatureMap()
ms.FeatureXMLFile().load("features.featureXML", fm)
df = fm.get_df()
print(df.head())

Summary

• pyOpenMS requires Python 3.8–3.11; newer or older versions trigger build errors.
• C++ compilation dependencies (GCC ≥ 7, CMake, Boost ≥ 1.65, Eigen ≥ 3.3) must be present when pre-built wheels are unavailable for your platform.
• System libraries including Qt5, zlib, libpng, and libtiff are runtime prerequisites not listed in the Python package metadata.
• Resource requirements (2+ GB RAM, 5+ GB disk) must be satisfied for source builds.
• Cache and network issues can be resolved by purging ~/.cache/pip or using manual wheel downloads with proxy configuration.

Frequently Asked Questions

Why does pyOpenMS fail with a PEP 517 build error?

This error indicates that your Python version is incompatible (pyOpenMS supports only 3.8–3.11) or that your system lacks the C++ compiler required to build the package from source. Verify your Python version and install build-essential (Linux) or Xcode Command Line Tools (macOS) before retrying installation.

Can I use pyOpenMS on Apple Silicon (M1/M2) Macs?

Yes, but you may need to install the correct architecture-specific versions of Boost and Eigen via Homebrew. Ensure you have Clang ≥ 6 and set CMAKE_PREFIX_PATH to point to your Homebrew installation directory if the linker cannot find the libraries automatically.

How much RAM is required to install pyOpenMS from source?

Compiling OpenMS from source requires more than 2 GB of RAM and approximately 5 GB of temporary storage for object files and linking. If your system or CI runner has limited resources, use a pre-built Docker image or ensure a compatible wheel is available for your Python version and platform.

Where are the detailed usage examples for pyOpenMS in the repository?

Detailed reference materials are located in scientific-skills/pyopenms/references/, including file_io.md for file format handling, signal_processing.md for smoothing algorithms, feature_detection.md for extraction workflows, and identification.md for peptide/protein identification pipelines. The main skill descriptor at scientific-skills/pyopenms/SKILL.md provides the installation guide and quick-start code snippets.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}