XenonPy can be installed using pip in 3.6 and 3.7 on Mac, Linux, and Windows. Alternatively, we recommend using the Docker Image if you have no installation preference. We have no plan to support Python 2.x. One of the main reasons is that the pymatgen library will not support Python 2 from 2019. See this link for details.

Using conda and pip

pip is a package management system for installing and updating Python packages, which comes with any Python distribution. Conda is an open source package management system and environment management system that runs on Windows, macOS, and Linux. Conda easily creates, saves, loads and switches between environments on your local computer.

XenonPy has 3 peer dependencies, which are PyTorch, pymatgen and rdkit. Before you install XenonPy, you have to install them. The easiest way to install all 3 packages is to use Conda. The following official tutorials will guide you through a successful installation.


For convenience, several environments preset are available at conda_env. You can use these files to create a runnable environment on your local machine.

$ conda env create -f <path_to_file>


For Unix-like (Linux, Mac, FreeBSD, etc.) system, the above command will be enough. For windows, additional tools are needed. We highly recommend you to install the Visual C++ Build Tools before creating your environment. Also, confirm that you have checked the Windows 10 SDK (assuming the computer is Windows 10) on when installing the build tools.

The following example shows how to create an environment from a preset step-by-step.

  1. Chose an environment preset and download it.

For example, you want to run XenonPy in python 3.7 with cuda10 supports. The xepy37_cuda10.yml preset will surely satisfy you. If curl has been installed, the following command will download the configuration file to your local machine.

$ curl -O
  1. Create the environment from file.

The following commands will rebuild the python environment based on the configuration file xepy37_cuda10.yml.

$ conda env create -f xepy37_cuda10.yml
  1. Enter the environment.

The environment name is the same as the configuration file. In this example, it’s xepy37_cuda10.

$ source activate xepy37_cuda10

# or

$ activate xepy37_cuda10

# or

$ conda activate xepy37_cuda10


Which command should be used is based on your system and your conda configuration.

  1. Install XenonPy

When you reached here, the remains are very simple. Using pip install xenonpy to install XenonPy into the environment.

$ pip install xenonpy

And, the old version could be updated as follow.

$ pip install -U xenonpy

Using docker


Docker is a tool designed to easily create, deploy, and run applications across multiple platforms using containers. Containers allow a developer to pack up an application with all of the parts it needs, such as libraries and other dependencies, into a single package. We provide the official docker images via the Docker hub.

Using docker needs you to have a docker installation on your local machine. If you have not installed it yet, follow the official installation tutorial to install docker CE on your machine. Once you have done this, the following command will boot up a jupyterlab for you with XenonPy inside. See here to know what other packages are available.

$ docker run --rm -it -v $HOME/.xenonpy:/home/user/.xenonpy -v <path/to/your/work_space>:/workspace -p 8888:8888 yoshidalab/xenonpy

If you have a GPU server/PC running Linux and want to bring the GPU acceleration to docker. Just adding --runtime=nvidia to docker run command.

$ docker run --runtime=nvidia --rm -it -v $HOME/.xenonpy:/home/user/.xenonpy -v <path/to/your/work_space>:/workspace -p 8888:8888 yoshidalab/xenonpy

For more information about using GPU acceleration in docker, see nvidia docker.

Permission failed

You may have a permission problem when you try to open/save jupyter files. This is because docker is a container system running like a virtual machine. Files will have different permission when be mounted onto a docker container. The simplest way to resolve this problem is changing the permission of failed files. You can open a terminal in jupyter notebook and type:

$ sudo chmod 666 permission_failed_file

This will change file permission to r+w for all users.

Installing in development mode

To use the latest development version distributed at Github repository, just clone the repository to create a local copy:

$ git clone

under the cloned folder, run the following to install XenonPy in development mode:

$ cd XenonPy
$ pip install -e .

To update XenonPy, use git fetch && git pull

$ git fetch && git pull


Contact us at issues and Gitter when you have trouble.

Please provide detailed information (system specification, Python version, and input/output log, and so on).