Installation

CDTools supports python >=3.9 and can be installed via pip as the the cdtools-py package on PyPI. If you plan to contribute to the code or need a custom environment, installation from source is also possible.

Option 1: Installation from PyPI

To install from PyPI, run:

$ pip install cdtools-py

or you can use uv for a faster installation:

$ uv pip install cdtools-py

Pytorch, a major dependence of CDTools, often needs to be installed with a specific CUDA version for machine compatability. If you run into issues with pytorch, consider first installing pytorch into your environment using the instructions on the pytorch site.

Option 2: Installation from source

Step 1: Download

The source code for CDTools is hosted on Github.

To download the source code, you can either clone the repository using git:

$ git clone https://github.com/cdtools-developers/cdtools.git

or you can download a zip file of the repository from the releases page.

Step 2: Install

Move to the directory where you downloaded the source code. It is recommended that you create a new python virtual environment to install CDTools into.

Installation using pip and uv. Editable mode is recommended for development purposes and is added with the -e flag.

$ pip install -e .

or using uv:

$ uv pip install -e .

To install the required test and documentation dependencies as well, use:

$ pip install -e ."[tests,docs]"

or using uv:

$ uv pip install -e ."[tests,docs]"

CDTools is reguarly tested with the latest versions of these packages and with python 3.9 through 3.14.

Required dependencies (see pyproject.toml for all details):

Optional dependencies for running tests:

Optional dependencies for building docs:

Optional step 4: Run The Tests

To ensure that the installation has worked correctly, it is recommended that you run the unit tests. Execute the following command from the top level directory of the git repository:

$ python -m pytest

If any tests fail, make sure that you have all the noted dependencies properly installed. If you do, and things still aren’t working, open an issue on the github page and we’ll get to the bottom of it.