Installation#

System requirements#

Recommended system resources to run tomoDRGN on real-world datasets:

  • CPU: 8+ cores

  • RAM: 128+ GB (enough to hold all particles + 25% margin if not using --lazy)

  • GPU: 1x Nvidia GPU with > 12 GB VRAM

  • Disk: 10-100 GB disk space for tomoDRGN outputs + fast local scratch disk if insufficient RAM to hold all particles

Minimum system resources to run tomoDRGN on toy datasets, develop source code, build documentation, etc.:

  • CPU: 4+ cores

  • RAM: 8+ GB

  • Disk: 2 GB disk space for toy dataset outputs

Creating a tomoDRGN environment#

We recommend creating separate virtual environments for separate software. Conda is a package manager that can create and manage such virtual environments, and can install the requisite Python and non-Python dependencies. Conda can be installed following the latest instructions here.

Once you have installed conda, run the commands below to create a tomoDRGN environment and install tomoDRGN.

# Create conda environment
conda create --name tomodrgn "python>=3.10, <3.13"
conda activate tomodrgn

# Clone source code and install tomoDRGN + dependencies
git clone https://github.com/bpowell122/tomodrgn.git
cd tomodrgn  # note: this directory is referred to as $TOMODRGN_SOURCE_DIR below
git checkout v1.0.0
python -m pip install .

If you did not see any errors, great! Your installation of tomoDRGN is ready to use, and you may confirm this by running tomoDRGN’s suite of CLI tests as described here.

Resolving potential installation errors#

If you did see errors during the installation process, here we describe some known issues and their solutions.

  • On an Ubuntu 24.04 system, tomoDRGN installation failed while installing the fastcluster dependency. The root cause appeared to be missing cmake installation.

    sudo apt install make
sudo apt install build-essential
sudo apt install cmake
# resume installation from ``python -m pip install .`` above

  • On an x86 Mac system, tomoDRGN installation failed while installing the torch dependency. The root cause appeared to be tomoDRGN’s requirement of torch>=2.3 which cannot be satisfied from PyPI / conda for x86 Macs. Therefore pytorch must be built from source for x86 Macs:

    pip install mkl-static mkl-include
git clone --recursive https://github.com/pytorch/pytorch
cd pytorch
conda install cmake ninja
pip install -r requirements.txt
python3 setup.py develop
# resume installation from ``python -m pip install .`` above