Installation

BiaPy can be installed and run locally on any Linux, Windows, or macOS platform using Docker or via the command line with Anaconda/Miniconda and Git. Alternatively, BiaPy can also be used on Google Colab. Each of these approaches is designed for different types of experiences and users (select the installation based on your level of expertise).

Prerequisites

Update your NVIDIA drivers for you GPUs in your system.
For Docker and graphical user interface (GUI) installations only: you will need to enable Virtualization Technology on your BIOS. Find here a useful link to do it.

Choose your installation method

Download BiaPy GUI for you OS:

Then, to use the GUI you will need to install Docker in your operating system. You can follow these steps:

In Windows you will need to install Docker Desktop with Windows Subsystem for Linux (WSL) activated. There is a good video on how you can do it here. Manually, the steps are these:

Install Ubuntu inside WSL. For that open PowerShell or Windows Command Prompt in administrator mode by right-clicking and selecting Run as administrator and type the following:
```
wsl --install
```
This command will enable the features necessary to run WSL and install the Ubuntu distribution of Linux. Then restart your machine and you can do it again so you can check that it is already installed.

Once the installation ends it will ask for a username and a password. This is not necessary, exit the installation by using Ctrl+C or by closing the window.

Then you need to make Ubuntu the default Linux distribution. List installed Linux distributions typing:
```
wsl --list -verbose
```
The one with * is the default configuration. So, if it is not Ubuntu, it can be changed by using the command:
```
wsl --set-default Ubuntu
```
Install Docker Desktop.

Check that everything is correct by opening Docker Desktop application, going to Configuration (wheel icon in the right top corner), in General tab the option WSL 2 should be checked.

Note

Whenever you want to run BiaPy through Docker you need to start Docker Desktop first.

You will need to follow the steps described here.

If you follow the steps and still have problems maybe you need to add your user to docker group:

sudo usermod -aG docker $USER
newgrp docker

To grant execution permission to the binary, enter the following command in a terminal:

chmod +x BiaPy

Then, the only thing you need to do is double-click in BiaPy binary you downloaded. The next step consists in select the specific workflow that aligns with your intended use.

We have two containers prepared to run BiaPy, one for the actual NVIDIA driver versions and another container for old drivers:

biapyx/biapy:latest-11.8: Ubuntu 22.04 SO with Pytorch 2.1 installed supporting CUDA 11.8 (container link).

biapyx/biapy:latest-10.2: Ubuntu 20.04 SO with Pytorch 1.12.1 installed supporting CUDA 10.2 (container link).

You need to check the CUDA version that you NVIDIA driver can handle. You can do that with nvidia-smi command in Linux/macOS or by running NVIDIA Control Panel in Windows. The driver information will tell you the maximum CUDA version it can handle. Select one of the above containers depending on your GPU driver. For instance, if the CUDA version it can handle is 12.0 you can use biapyx/biapy:latest-11.8 container.

To install Docker in your operating system, you can follow these steps:

In Windows you will need to install Docker Desktop with Windows Subsystem for Linux (WSL) activated. There is a good video here. Let’s start the installation:

Install Ubuntu inside WSL. For that open PowerShell or Windows Command Prompt in administrator mode by right-clicking and selecting Run as administrator and type the following:
```
wsl --install
```
This command will enable the features necessary to run WSL and install the Ubuntu distribution of Linux. Then restart your machine and you can do it again so you can check that it is already installed.

Once the installation ends it will ask for a username and a password. This is not necessary, exit the installation by using Ctrl+C or by closing the window.

Then you need to make Ubuntu the default Linux distribution. List installed Linux distributions typing:
```
wsl --list -verbose
```
The one with * is the default configuration. So, if it is not Ubuntu, it can be changed by using the command:
```
wsl --set-default Ubuntu
```
Install Docker Desktop.

Check that everything is correct by opening Docker Desktop application, going to Configuration (wheel icon in the right top corner), in General tab the option WSL 2 should be checked.

Note

Whenever you want to run BiaPy through Docker you need to start Docker Desktop first.

You will need to follow the steps described here.

If you follow the steps and still have problems maybe you need to add your user to docker group:

sudo usermod -aG docker $USER
newgrp docker

The next step consists in select the specific workflow that aligns with your intended use.

To use BiaPy via the command line, you will need to set up a conda environment. To do this, you will first need to install Anaconda/Miniconda. For detailed installation instructions based on your operating system, please see the following links: Windows, macOS and Linux. Then you need to create a conda environment through a terminal:

# Create and activate the environment
conda create -n BiaPy_env python=3.10
conda activate BiaPy_env

Then you will need to install BiaPy package:

pip install biapy

# Then install Pytorch 2.2.0 + CUDA 11.8
pip install torch==2.2.0 torchvision==0.17.0 torchaudio==2.2.0 --index-url https://download.pytorch.org/whl/cu118
pip install timm torchmetrics

Note

The PyPI package does not install Pytorch because there is no option to build that package specifying exactly the CUDA version you want to use. There are a few solutions to set up pyproject.toml with poetry and specify the CUDA version, as discussed here, but then PyPI package can not be built (as stated here).

To clone the repository you will need to install git, a free and open source distributed version control system. Git will allow you to easily download the code with a single command. You can download and install it here. For detailed installation instructions based on your operating system, please see the following links: Windows, macOS and Linux.

Once you have installed Anaconda and git, you will need to t, you will need to open a terminal to complete the following steps. Then, you are prepared to download BiaPy repository by running this command in the terminal

git clone https://github.com/BiaPyX/BiaPy.git

This will create a folder called BiaPy that contains all the files of the library’s official repository. Then you need to create a conda environment and install the dependencies.

You need to check the CUDA version that you NVIDIA driver can handle. You can do that with nvidia-smi command in Linux/macOS or by running NVIDIA Control Panel in Windows. The driver information will tell you the maximum CUDA version it can handle. We here provide two stable installations, one based in CUDA 11.8 and another one with an older version of Pytorch and with CUDA 10.2 (BiaPy will work anyway). Once you have checked it, proceed with the installation depending on the CUDA version:

# Install Pytorch 2.2.0 + CUDA 11.8
pip install torch==2.2.0 torchvision==0.17.0 torchaudio==2.2.0 --index-url https://download.pytorch.org/whl/cu118
pip install timm torchmetrics

cd BiaPy
pip install --editable .

# Install Pytorch 1.12.1 + CUDA 10.2
conda install pytorch==1.12.1 torchvision==0.13.1 torchaudio==0.12.1 cudatoolkit=10.2 -c pytorch
pip install timm torchmetrics

cd BiaPy
pip install --editable .

Verify installation:

python -c 'import torch; print(torch.__version__)'
>>> 2.1.0
python -c 'import torch; print(torch.cuda.is_available())'
>>> True

From now on, to run BiaPy you will need to just activate the environment:

conda activate BiaPy_env

The next step consists in select the specific workflow that aligns with your intended use.