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#

For most users, the quickest way to get started is:

# Create conda environment
conda env create -f env.yml
conda activate mdaviz

# Install PyQt6 (not available in conda-forge for all platforms)
pip install PyQt6 Qt6

# Install mdaviz
pip install mdaviz

pip Installation#

Released versions of mdaviz are available on PyPI.

If you have pip installed, then you can install:

$ pip install mdaviz

Note: PyQt6 and Qt6 are required dependencies that may need to be installed separately:

pip install PyQt6 Qt6

Source Installation#

The latest development versions can be downloaded from the GitHub repository listed above:

$ git clone https://github.com/BCDA-APS/mdaviz

To install from the source directory using pip in editable mode:

$ cd mdaviz
$ python -m pip install -e .

For development installation with all dependencies:

$ cd mdaviz
$ python -m pip install -e ".[dev]"

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 - tiled - Data access - 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:

$ 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"

Command-line Options#

The application supports several command-line options:

$ mdaviz --log debug    # Enable debug logging
$ mdaviz --help         # Show help (future enhancement)

Platform-Specific Notes#

Linux#

  • Most dependencies available via conda-forge

  • PyQt6 may need to be installed via pip

  • X11 libraries required for GUI

macOS#

  • Qt6 and PyQt6 available via conda-forge or pip

  • May need to handle code signing for distribution

  • Tested on macOS 12+

Windows#

  • Visual Studio Build Tools may be required for some dependencies

  • PyQt6 and Qt6 available via pip

  • Tested on Windows 10/11

Troubleshooting#

Common Installation Issues#

PyQt6 Import Error: .. code-block:: bash

# Ensure PyQt6 is installed pip install PyQt6 Qt6

# Verify installation python -c “import PyQt6; print(‘PyQt6 installed successfully’)”

Conda Environment Issues: .. code-block:: bash

# Recreate environment if needed conda env remove -n mdaviz conda env create -f env.yml conda activate mdaviz pip install PyQt6 Qt6

Permission Errors: .. code-block:: bash

# Use user installation if system-wide fails pip install –user mdaviz pip install –user PyQt6 Qt6

Missing Dependencies: .. code-block:: bash

# Install all dependencies explicitly conda install matplotlib scipy lmfit tiled pyyaml pip install PyQt6 Qt6