Detailed installation instructions¶
Choose the installation method that fits how you want to use xrt. The options below start with a ready-to-use environment and progress to managing your own Python environment.
Pixi¶
Pixi sets up Python, xrt from GitHub, and all its dependencies on Windows,
Linux and macOS. Start with a single pixi.toml file and launch xrtQook
with pixi run -e gui xrtQook.
See Installing and running xrt with Pixi for installing Pixi on your platform, running xrt, and setting up a developer checkout.
WinPython on Windows¶
WinPython is a portable Python distribution for Windows. Choose a distribution that includes the scientific packages and Spyder IDE. It provides most of the dependencies and lets you keep several Python environments side by side.
Download the xrt source archive and unzip it to a suitable location. Open the command prompt supplied with WinPython and install the packages listed under Running from source without installation; pip keeps already installed packages that satisfy the requirements.
You can then open an example script or xrt/gui/xrtQookStart.py from the
source tree in Spyder. Run scripts from their own directory and use Spyder’s
external terminal for scripts that use multiprocessing (see
Spyder settings).
Running from source without installation¶
xrt itself does not require compilation and can be used directly from its source tree. This is useful for development or for sharing one copy of xrt between several Python environments. Each environment needs its own dependencies. For an environment managed by Pixi, use the developer workflow in Installing and running xrt with Pixi.
Clone the GitHub repository or download and unzip its source archive. The current source requires Python 3.9 or newer. The requirements are recorded in pyproject.toml. Install the scientific and GUI dependencies in the Python environment you intend to use:
python -m pip install numpy scipy matplotlib sphinx sphinxcontrib-jquery
python -m pip install distro colorama pyopencl pyopengl siphash24 freetype-py
python -m pip install PyQt5 PyQtWebEngine qtpy qtpynodeeditor numpy-stl
For the EPICS integration, also install its optional dependencies:
python -m pip install softioc pyepics phoebusgen
Building the documentation additionally requires sphinx-tabs.
Run scripts from their directory within examples or tests. Many of
these scripts add a relative path to the source tree, so their working
directory matters. Edits to the Python source take effect when the script or
application is restarted.
If you have several copies of xrt, check which one Python imports:
python -c "import xrt; print(xrt.__file__)"
Using xrt as a library: pip and Conda¶
These options suit users who already have a Python environment and an IDE and want to import xrt in their own scripts.
pip
Install the published release from PyPI into your chosen Python environment:
python -m pip install xrt
To include the Qt GUI dependencies, use python -m pip install "xrt[pyqt5]".
For a PyPI prerelease, add --pre to the install command.
Conda
Install the conda-forge package in your chosen Conda environment:
conda install conda-forge::xrt
PyPI and conda-forge releases may differ from each other and from the current GitHub source. Check the available versions on PyPI and conda-forge.
Installing from GitHub source
To install the downloaded or cloned source as a library, navigate to the
directory containing pyproject.toml and run:
python -m pip install ".[all]"
This includes all optional dependencies. Add -e for an editable installation
if you want Python to use subsequent changes in that source tree.
Spyder
For xrt scripts that use multiprocessing, select Run in external terminal in Spyder’s Run menu (Spyder 6), or configure the script to use an external terminal in earlier versions. See the Spyder FAQ for run configuration options.
PyOpenCL and OpenCL runtimes¶
OpenCL calculations require an OpenCL implementation (runtime) in addition to PyOpenCL. This can come with a graphics card driver or a CPU runtime. Installing PyOpenCL alone does not install a GPU driver. Graphics cards with a high FP64/FP32 ratio are advantageous for double-precision calculations.
PyOpenCL provides binary wheels for common platforms, so installing it with pip usually does not require development headers or compiling from source. See the PyOpenCL installation instructions for current platform-specific runtime choices, including CPU runtimes.
On Linux, if a conda-forge environment cannot find system OpenCL drivers, install the package that exposes the system ICD files to that environment:
conda install -c conda-forge ocl-icd-system
For a Pixi environment, run
pixi add --platform linux-64 ocl-icd-system in its workspace instead.
For a CPU runtime on Linux or macOS, PoCL is another option: use
conda install -c conda-forge pocl. With Pixi, add it for the relevant
platform, for example pixi add --platform linux-64 pocl on Linux.
Linux GUI system dependencies¶
xrtQook and xrtGlow need system OpenGL libraries. In a Wayland session, the GLX backend also requires XWayland. The following packages were tested on RHEL 9 with KDE/Wayland:
sudo dnf install \
mesa-libGL mesa-dri-drivers \
libglvnd-glx \
xorg-x11-server-Xwayland
On Ubuntu Desktop, these dependencies are normally installed by default. If the viewer fails to start, check that the following packages are installed:
dpkg -l libgl1 libglx0 libglx-mesa0 libgl1-mesa-dri xwayland
Installed packages have ii at the beginning of their output line.
To install any missing packages, run:
sudo apt update
sudo apt install \
libgl1 libglx0 libglx-mesa0 libgl1-mesa-dri xwayland
These are operating-system dependencies and are needed even when Python packages are managed by Pixi or Conda.
