Install with pip

This guide covers installation of MuscleX using Python’s pip package manager.

Prerequisites

MuscleX is tested with Python 3.10, but should work with Python 3.8 through 3.12.

Run the appropriate command for your platform:

If your version falls within the supported range, there’s no need to install Python 3.10.

sudo apt update
sudo apt install python3-pip python3-dev build-essential gfortran

brew install python gcc

It is strongly recommended to install MuscleX inside a virtual environment to avoid conflicts with other Python packages.

Note: venv is recommended for pip installations. If you are using Conda, refer to the Conda installation instructions instead.

python3 -m venv musclex_env
source musclex_env/bin/activate

python -m venv musclex_env
musclex_env\Scripts\activate

conda create -n musclex python=3.10
conda activate musclex

pip install --upgrade musclex

pip install musclex==1.24.0

pip install --upgrade git+https://github.com/biocatiit/musclex.git

pip install git+https://github.com/biocatiit/musclex.git@v1.15.2

To confirm that MuscleX was installed correctly:

pip list | grep musclex

After activation, run any program like so:

musclex xv

To deactivate:

deactivate              # venv
conda deactivate        # conda

Missing Python.h: Install Python development headers:

sudo apt install python3-dev        # Debian/Ubuntu
sudo dnf install python3-devel      # Fedora

Build errors: Try installing using conda instead, or ensure all required build tools are available.
Missing GUI: If you get GUI-related import errors, ensure PyQt5 or PySide2 is installed:
```
pip install PyQt5
```
Missing C extension or iNaT error:
```
pip install -U pandas
```
Qt platform plugin error (e.g. qt.qpa.plugin: Could not load the Qt platform plugin "xcb"):

First, swap opencv-python (which bundles its own Qt and frequently clashes with the system Qt) for the headless build:
```
pip uninstall opencv-python
pip install opencv-python-headless
```
If needed, pin to an older OpenCV release:
```
pip install opencv-python==4.2.0.32
```
On Linux, the xcb plugin also requires several native XCB / X11 libraries. On Debian/Ubuntu install:
```
sudo apt update
sudo apt install libxcb-cursor0 libxkbcommon-x11-0 libxcb-xinerama0
sudo apt install libxcb-render-util0 libxcb-image0 libxcb-keysyms1 libxcb-icccm4
sudo apt install x11-apps qt6-base-plugins qt6-base-dev
sudo apt-get install python3-opencv
```
To diagnose which specific library is missing, rerun with Qt plugin debug output:
```
QT_DEBUG_PLUGINS=1 musclex xv
```
See also the cross-platform troubleshooting guide.

Pip dependency issues: Ensure wheel and numpy are up to date:

pip install --upgrade wheel
pip install --upgrade numpy

If you need to match the tested version or experience compatibility issues, follow these steps to install Python 3.10.

sudo apt install python3.10 python3.10-venv python3.10-dev

To use it:

python3.10 -m venv musclex_env

brew install python@3.10

To use it:

python3.10 -m venv musclex_env

py -3.10 -m venv musclex_env

Update via pip:

pip install -U musclex

Without updating dependencies:

pip install -U --no-deps musclex

From GitHub:

pip install --upgrade git+https://github.com/biocatiit/musclex.git

If needed:

pip install musclex

Note: This may interfere with other Python packages on your system. Use with caution.