Installation#
Requirements#
idtracker.ai is a Python package, available on PyPI, that runs on Windows, Linux and macOS.
idtracker.ai identifies animals with neural networks (using PyTorch), so a dedicated GPU is highly recommended:
an NVIDIA or AMD GPU with 4 GB of VRAM or more, or
on macOS 12.3 or later, an Apple silicon (M-series) chip or an AMD GPU.
Without a GPU you can still use some features; see Install without a graphics device.
idtracker.ai needs a capable computer
We recommend at least 12 GB of RAM (more for long, high-resolution videos) and a multi-core CPU (Intel i5, AMD Ryzen 5 or better).
Installation takes four steps:
Check your NVIDIA drivers (NVIDIA GPUs only).
Install idtracker.ai and PyTorch.
Check Nvidia drivers#
Only for NVIDIA GPUs
Do not install NVIDIA drivers if your computer has no NVIDIA GPU.
Apple and AMD users: skip to Check Conda environments, and pay special attention to step 3 of Install idtracker.ai to get the right PyTorch command.
No GPU: see Install without a graphics device.
To use an NVIDIA GPU, your drivers must support CUDA 12.0 or later. To check, open a terminal (Anaconda Prompt on Windows) and run:
nvidia-smi
The output should look similar to this:
nvidia-smi output#+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.183.01 Driver Version: 535.183.01 CUDA Version: 12.2 |
|-------------------------------+----------------------+----------------------+
| GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|===============================+======================+======================|
| 0 NVIDIA GeForce ... Off | 00000000:01:00.0 Off | N/A |
| N/A 60C P0 N/A / 35W | 5MiB / 4096MiB | 0% Default |
| | | N/A |
+-------------------------------+----------------------+----------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=============================================================================|
| 0 N/A N/A 2186 G /usr/lib/xorg/Xorg 4MiB |
+-----------------------------------------------------------------------------+
Look at “CUDA Version” in the top-right corner:
12.0 or later: your drivers are ready. Continue with Check Conda environments.
Lower than 12.0, or the command fails: update (or install) your NVIDIA drivers as described below.
Tip
Avoid installing critical drivers like NVIDIA’s by hand when possible. Let your operating system install and update them.
First, let Windows install the drivers itself. Open Windows Update with:
control update
Check for updates, install them, and reboot when prompted.
If the nvidia-smi output has not changed, open NVIDIA’s GeForce Experience app (or install it from NVIDIA's website).
Nvidia’s GeForce Experience application#
In the DRIVERS tab, click CHECK FOR UPDATES, update your drivers, and reboot when asked. If this does not work either, download the drivers manually from the NVIDIA website.
First, let Ubuntu install the drivers itself with a general update:
sudo apt update
sudo apt upgrade
and reboot if asked.
If the nvidia-smi output has not changed, open Ubuntu’s Software & Updates app (or launch it with software-properties-gtk).
Ubuntu’s Software & Updates application#
Ubuntu’s Software & Updates application#
In the Additional Drivers tab, select the NVIDIA driver marked (proprietary, tested) and click Apply Changes. Wait for the installation to finish and reboot when prompted.
Check Conda environments#
We recommend installing idtracker.ai in a Conda environment. A Conda environment is an isolated set of packages, with its own Python version, so that idtracker.ai’s dependencies do not conflict with other software on your computer.
Check whether Conda is installed by running:
conda
If you get an error like conda: command not found, install Miniconda (a minimal Conda installation, recommended) or Anaconda from the official website, or follow their guide.
Warning
On a Mac with an M-series chip, choose the Apple silicon installer, not the Intel chip one.
Install idtracker.ai#
With your drivers ready and Conda installed, run the following commands in a terminal (Anaconda Prompt on Windows):
Create a Conda environment called idtrackerai with Python 3.13 (Python 3.10 to 3.13 are supported). You can choose another name for the environment:
conda create -n idtrackerai python=3.13
Activate the environment:
conda activate idtrackerai
Install PyTorch and Torchvision. Get the right command for your computer from the PyTorch website, selecting:
PyTorch Build: Stable
Your OS: your operating system
Package: Pip
Language: Python
Compute Platform: the highest CUDA version for NVIDIA GPUs, ROCm for AMD GPUs, or CPU if your computer has no GPU (on macOS, the default option uses Apple silicon and AMD GPUs automatically)
For example, on Linux with an NVIDIA GPU, the command looks like this:
pip3 install torch torchvision --index-url https://download.pytorch.org/whl/...
Warning
Do not copy this command: the right one depends on your computer. Get it from the PyTorch website.
Install idtracker.ai from PyPI:
pip install idtrackerai
Tip
If this step fails, see Installation Troubleshooting.
Important
idtracker.ai is only available while its Conda environment is active. Every time you open a new terminal, activate the environment before running any idtracker.ai command:
conda activate idtrackerai
Test the installation#
In a terminal (Anaconda Prompt on Windows), activate the environment and run the test:
conda activate idtrackerai
idtrackerai_test
The test copies an 18-second video, test_B.avi, to the current directory, tracks it, and saves the results in a session_test folder.
The test takes 1 to 6 minutes with a GPU, and 10 to 50 minutes without one. When it finishes, the last line should be:
INFO Test passed successfully in 00:??:?? with version 6.0.15
which means that idtracker.ai is installed correctly!
If the test fails, see Installation Troubleshooting .
See also
For a more demanding test, try this high-quality video of 60 zebrafish with its optimal parameters:
name = 'testing_60zebrafish'
video_paths = ['zebrafish_60_1.avi']
intensity_ths = [0, 25]
area_ths = [80, 10000]
number_of_animals = 60
use_bkg = true
roi_list = [
"+ Ellipse {'center': [1924, 1800], 'axes': [1769, 1789], 'angle': 101}",
]
Our data repository has more high-quality videos, with their parameters and tracking results:
Install without a graphics device#
Without a GPU, you have two options.
Install without PyTorch. The Segmentation app, the Validator and the Video Generator do not use PyTorch. To use only these tools, follow steps 1, 2 and 4 of Install idtracker.ai and skip step 3.
This is useful when tracking runs on a remote computer with a GPU: set the parameters on your computer, track on the remote one, then validate and process the results on your computer again.
Install PyTorch for the CPU. Follow all the steps of Install idtracker.ai, selecting Compute Platform: CPU in step 3. This is enough to track single animals or to Track without identities, because these do not use the identification networks. Tracking several animals with identities also works, but the networks run very slowly on a CPU, so it is impractical for long videos.
Update idtracker.ai#
To update from version 5 or later to the current version (6.0.15), activate the environment and run:
python -m pip install --upgrade idtrackerai
Version 4 and older used a different Python version, so they cannot be upgraded in place. Uninstall the old environment and install the new version from scratch.
Uninstall#
To delete the Conda environment and everything installed in it, deactivate it and run:
conda remove -n idtrackerai --all