Installation Guide#
The mdaviz package is available for installation by pip or from source.
Please [report](BCDA-APS/mdaviz#new) any issues you encounter or feature requests, too.
Quick Install#
Option 1: Download the executable from the GitHub Releases page.#
Download the executable for your platform from the GitHub Releases page.
Run the executable.
cd Download # Navigate to the directory where you downloaded the executable
mdaviz # Linux & MacOS
mdaviz.exe # Windows; you can also double click on the executable to start the application.
Note:
The executable is self contained and does not require a conda environment.
The Linux executable available on the GitHub Releases page requires recent Linux distribution and does not currently work on APS machines. See below to build the executable manually.
On MacOS, the application can be slow to start when running from the executable, but once loaded, it is as fast as when running from the conda environment.
Option 2: Install from PyPI (Recommended for users)#
For most users, the quickest way to get started is to install from PyPI.
# Create a simple conda environment
conda create -n mdaviz python=3.12
conda activate mdaviz
pip install PyQt6 Qt6
# Install mdaviz
pip install mdaviz
Note:
PyQt6 and Qt6 are required dependencies that may need to be installed separately.
At the APS: PyQt6 requires to install the following library:
sudo yum install xcb-util-cursor
Option 3: Install from source (Recommended for developers)#
For development and contributing, it is strongly recommended to use the provided conda environment. This ensures all dependencies (including PyQt6) are available and compatible.
# Clone the github repository
git clone https://github.com/BCDA-APS/mdaviz.git
cd mdaviz
# Create and activate conda environment
conda env create -f env.yml
conda activate mdaviz
pip install PyQt6 Qt6
# Install in development mode
pip install -e .
Note:
PyQt6 and Qt6 are required dependencies that may need to be installed separately.
At the APS: PyQt6 requires to install the following library:
sudo yum install xcb-util-cursor
Required Libraries#
The repository’s env.yml file lists the additional packages
required by mdaviz. Most packages are available as conda packages
from https://anaconda.org. The others are available on
https://PyPI.python.org.
Core Dependencies:
PyQt6 (6.9.1+) - Qt6 bindings for Python
Qt6 (6.9.0+) - Qt6 framework
matplotlib - Plotting library
scipy - Scientific computing
lmfit - Curve fitting
PyYAML - YAML processing
Development Dependencies:
pytest - Testing framework
ruff - Code linting and formatting
mypy - Type checking
pre-commit - Git hooks
Running the Application#
For pip installation, activate the conda environment and start the application:
conda activate mdaviz
mdaviz
For source installation, navigate to the mdaviz directory then use the same commands:
# Navigate to the mdaviz directory
cd mdaviz
conda activate mdaviz
mdaviz
You can also create an alias for convenience; e.g., in bash:
alias start_mdaviz="conda activate mdaviz; mdaviz"
Troubleshooting#
Common Installation Issues (Windows)#
PyQt6 Import Error:
# Ensure PyQt6 is installed
pip install PyQt6 Qt6
# Verify installation
python -c "import PyQt6; print('PyQt6 installed successfully')"
Conda Environment Issues:
# Recreate environment if needed
conda env remove -n mdaviz
conda env create -f env.yml
conda activate mdaviz
pip install PyQt6 Qt6
Missing Dependencies:
# Install all dependencies explicitly
conda install matplotlib scipy lmfit pyyaml
pip install PyQt6 Qt6
Build Executables#
Clone the repository and install the dependencies:
git clone https://github.com/BCDA-APS/mdaviz.git
cd mdaviz
conda env create -f env.yml
conda activate mdaviz
pip install -e ".[dev,build]"
To build the executables, install pyinstaller (available via pip) and use the following commands:
# Install pyinstaller via conda
conda install -c conda-forge pyinstaller
# OR install pyinstaller via pip
pip install pyinstaller
# Build the spec file
pyi-makespec --onefile --windowed --name mdaviz src/mdaviz/app.py --add-data "src/mdaviz/resources:mdaviz/resources"
# Build the executable
pyinstaller mdaviz.spec
You can start the application by running the executable:
./dist/mdaviz # Linux & MacOS
dist\mdaviz.exe # Windows; you can also double click on the executable to start the application.
Notes:
The executable can be run without activating the conda environment.
On MacOS, the application can be slow to start when running from the executable, but once loaded, it is as fast as when running from the conda environment.