Installation

Create environment

Creating a conda environment is not required but recommended.

Miniconda installation and setup

Miniconda is a free minimal installer for conda.

Here are some quick instructions to help you set up the latest Miniconda installer for your system:

WindowsmacOSLinux

The easiest way to install Miniconda on Windows is through the graphical interface installer. Follow these steps:

Download the installer here.
Run the installer and follow the on-screen instructions.
When the installation finishes, open Anaconda Prompt (miniconda3) from the Start menu.

The easiest way to install Miniconda on macOS is through the graphical interface installer. Follow these steps:

Download the correct installer for your processor version. If you are unsure about your version, check here.
- For Intel processors, download x86
- For Apple Silicon (M1/M2/M3 etc) processors, download arm64
Run the installer and follow the on-screen instructions.

These four commands quickly and quietly install the latest 64-bit version of the installer and then clean up after themselves. To install a different version or architecture of Miniconda for Linux, change the name of the .sh installer in the wget command.

mkdir -p ~/miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm -rf ~/miniconda3/miniconda.sh

After installing, initialize your newly-installed Miniconda. The following commands initialize for bash and zsh shells:

~/miniconda3/bin/conda init bash
~/miniconda3/bin/conda init zsh

Once you have conda installed, open your terminal and create a new enviroment:

conda create -n qim3d python=3.11

After the environment is created, activate it by running:

conda activate qim3d

Remember, if you chose to create an environment to install qim3d, it needs to be activated each time before using the library.

Install using `pip`

The latest stable version can be simply installed using pip. Open your terminal and run:

pip install qim3d

After completing the installation, you can verify its success by running one or both of the following commands:

qim3d

or:

pip show qim3d

If either command displays information about the qim3d library, the installation was successful.

Optional dependencies

qim3d includes some features that require additional Python packages. These are not installed by default, keeping the base library lightweight.

You can install optional dependencies for specific features:

Feature	Optional dependency	Install command
Deep-learning / model training	`torch`, `torchvision`, `torchinfo`, `monai`	`pip install qim3d[deep-learning]`
GUI / interactive tools	`gradio`	`pip install qim3d[gui]`
All optional features	All of the above	`pip install qim3d[all]`

Note

If you try to run a script that requires an optional dependency and it is not installed, qim3d will show a ImportError with instructions on how to install the missing dependency.

Installing Multiple Features

You can install multiple optional dependency groups simultaneously by separating the names with a comma, without spaces, inside the brackets.
For example, to install both the gui features and the deep-learning features, use the following command:

pip install qim3d[gui,deep-learning]

Installing qim3d And CIL In The Same Environment

CIL is an open-source Python framework for tomographic imaging, and is often used together with qim3d. To install both packages in the same environment, create and activate a new environment, then run:

conda install -c conda-forge -c ccpi cil=26.0.0 && pip install qim3d

This installs CIL first, and then qim3d. The installation order is important: CIL must be installed before qim3d to avoid package conflicts.

Troubleshooting

Here are some solutions for commonly found issues during installation and usage of qim3d.

Get the latest version

The library is under constant development, so make sure to keep your installation updated:

pip install --upgrade qim3d