We assume that you have a recent python installation (python 3.7+). It this is not the case you can make one following the dedicated section on how to get a miniconda installation.

Basic installation

The Xsuite packages can be cloned from GitHub and installed with pip:

$ git clone
$ pip install -e xobjects

$ git clone
$ pip install -e xline

$ git clone
$ pip install -e xpart

$ git clone
$ pip install -e xtrack

$ git clone
$ pip install -e xfields

(The installation without the -e option is still untested).

This installation allows using Xsuite on CPU. To use Xsuite on GPU, with the cupy and/or pyopencl you need to install the corresponding packages, as described in the dedicated section.

Optional dependencies

To import MAD-X lattices you will need the cpymad package, which can be installed as follow:

$ pip install cpymad

To import lattices from a set of sixtrack input files (fort.2, fort.3, etc.) you will need the sixtracktools package, which can be installed as follow:

$ git clone
$ pip install -e sixtracktools

Some of the tests rely on pyheadtail to test the corresponding interface:

$ git clone
$ pip install cython
$ pip install -e pyheadtail

GPU support

In the following section we describe the steps to install the two supported GPU platforms, i.e. cupy and pyopencl.

Installation of cupy

In order to use the cupy context, the cupy package needs to be installed. In Anacoda or Miniconda (if you don’t have Anaconda or Miniconda, see dedicated section on how to get a miniconda installation) this can be done as follows for example for CUDA version 10.1.243:

$ conda install mamba -n base -c conda-forge
$ pip install cupy-cuda101
$ mamba install cudatoolkit=10.1.243

Remember to check your CUDA version e.g. via $ nvcc --version and use the appropriate tag.

Installation of PyOpenCL

In order to use the pyopencl context, the PyOpenCL package needs to be installed. In Anacoda or Miniconda this can be done as follows:

$ conda config --add channels conda-forge
$ conda install pyopencl

Check that there is an OpenCL installation in the system:

$ ls /etc/OpenCL/vendors

Make the OpenCL installation visible to pyopencl:

$ conda install ocl-icd-system

For the PyOpenCL context we will need the gpyfft and the clfft libraries. For this purpose we need to install cython.

$ pip install cython

Then we can install clfft.

$ conda install -c conda-forge clfft

We locate the library and headers here:

$ ls ~/miniconda3/pkgs/clfft-2.12.2-h83d4a3d_1/
# gives: include  info  lib

(Or locate the directory via find $(dirname $(dirname $(type -P conda)))/pkgs -name "clfft*" -type d .)

We obtain gpyfft from github:

$ git clone

and we install gpyfft with pip providing extra flags as follows:

$ pip install --global-option=build_ext --global-option="-I/home/giadarol/miniconda3/pkgs/clfft-2.12.2-h83d4a3d_1/include" --global-option="-L/home/giadarol/miniconda3/pkgs/clfft-2.12.2-h83d4a3d_1/lib" gpyfft/

Alternatively (if the command above does not work) we can edit the of gpyfft to provide the right paths to your clfft installation (and potentially the OpenCL directory of your platform):

if 'Linux' in system:
    CLFFT_DIR = os.path.expanduser('~/miniconda3/pkgs/clfft-2.12.2-h83d4a3d_1/')
    CLFFT_LIB_DIRS = [r'/usr/local/lib64']
    CLFFT_INCL_DIRS = [os.path.join(CLFFT_DIR, 'include'), ] # remove the 'src' part
    CL_INCL_DIRS = ['/opt/rocm-4.0.0/opencl/include']

And install gpyfft locally.

$ pip install -e gpyfft/

Install Miniconda

If you don’t have a miniconda installation, you can quickly get one ready for xsuite installation with the following steps.

On Linux

$ cd ~
$ wget
$ bash
$ source miniconda3/bin/activate
$ pip install numpy scipy matplotlib pandas ipython pytest

On MacOS

$ cd ~
$ curl >
$ bash
$ source miniconda3/bin/activate
$ conda install clang_osx-64
$ pip install numpy scipy matplotlib pandas ipython pytest