Installation

Installing Python packages for ParaView can be non‑trivial. We recommend using virtual environments so packages are properly linked to ParaView. For this we present two methods:

• Installation

  • Use Conda to install ParaView (recommended)

  • Link package to an existing ParaView installation using venv

Note

The ParaView package available via Conda lacks MPI support. If you need to visualize large simulations, we recommend linking to an existing ParaView build with MPI support.

Use Conda to install ParaView (recommended)

If you do not have Conda/conda-forge/Miniforge, install Miniforge:

wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

Activate Conda (adjust path if you installed Miniforge elsewhere):

source ~/miniforge3/bin/activate

1. Clone the repository:

   git clone https://github.com/sapphirepp/sapphireppplot.git
   cd sapphireppplot
   

2. Create sapplot Conda environment and install ParaView and other prerequisites:

   conda env create -f environment.yml
   conda activate sapplot
   

3. Install sapphireppplot (example developer mode):

   pip install -e '.[dev]'
   

After this, scripts should work from the terminal with python, pvpython, or pvbatch, and inside the ParaView GUI. Before running python or launching the ParaView GUI, always activate the Conda environment:

conda activate sapplot
python script.py args  # run script
paraview               # launch GUI

Link package to an existing ParaView installation using venv

This assumes you already have recent ParaView version (> v6.0.1) and pvpython installed. Install it from the ParaView download page if needed, or follow the instructions to compile ParaView from source.

The Python version used by the virtual environment must match the Python used by pvpython. Check the version with:

pvpython -c "import sys; print(sys.executable, sys.version)"

1. Create a virtual environment (venv):
   Manually ensure to use a matching Python version!

   python -m venv /path/to/venv/sapplot
   

   (Alternatively you can use Conda or virtualenv, see above. But do not install ParaView in the virtual environment, as this can lead to compatibility issues.)

2. Activate the venv (note the /bin/activate):

   source /path/to/venv/sapplot/bin/activate
   

3. Install the package (example from GitHub):

   pip install git+https://github.com/sapphirepp/sapphireppplot.git
   

Run scripts with pvbatch or start the GUI, pointing ParaView to the venv:

pvbatch --venv=/path/to/venv/sapplot script.py args  # run script
paraview --venv=/path/to/venv/sapplot                # launch GUI

Note

Do not run scripts with the virtual environment’s python binary directly — it does not provide ParaView’s compiled Python extensions. Always use pvpython/pvbatch or start ParaView with --venv so ParaView can load the environment.