Installing `zamba`¶

Zamba has been developed and tested on macOS, Ubuntu Linux, and Windows for both CPU and GPU configurations.

To install `zamba`¶

1. Install prerequisites¶

Prerequisites:

Python >= 3.11
FFmpeg

Python >= 3.11¶

We recommend Python installation using Anaconda for all platforms. For more information about how to install Anaconda, here are some useful YouTube videos of installation:

FFmpeg > 4.3 (only needed for video workflows)¶

FFmpeg is an open source library for loading videos of different codecs. Using FFmpeg means that zamba can be flexible in terms of the video formats we support. FFmpeg can be installed on all different platforms, but requires some additional configuration depending on the platform.

Linux (Ubuntu/Debian): sudo apt update && sudo apt install ffmpeg
macOS: Install Homebrew, then brew install ffmpeg
Windows: Install via Chocolatey (choco install ffmpeg) or download from ffmpeg.org and add the bin folder to your PATH.

To check that FFmpeg is installed, run ffmpeg -version:

$ ffmpeg -version
ffmpeg version 4.4 Copyright (c) 2000-2021 the FFmpeg developers
...

2. Install `zamba`¶

We recommend uv for installing Python packages and managing environments. Install uv if you haven't already. On macOS, run these commands in the terminal (⌘+space, "Terminal"). On Windows, run them in a command prompt, or if you installed Anaconda an anaconda prompt (Start > Anaconda3 > Anaconda Prompt).

zamba is split into optional extras so you only install the dependencies you need. With uv (recommended):

Video workflows (species classification in camera trap videos):
```
$ uv pip install zamba[video]
```
Image workflows (species classification in camera trap images):
```
$ uv pip install zamba[image]
```
Both video and image workflows:
```
$ uv pip install zamba[video,image]
```

With pip, use the same extras: pip install zamba[video], pip install zamba[image], or pip install zamba[video,image]. To install from the latest GitHub source instead of PyPI: pip install "zamba[video] @ https://github.com/drivendataorg/zamba/releases/latest/download/zamba.tar.gz" (and similarly for other extras).

To check what version of zamba you have installed:

$ uv pip show zamba

Or with pip: pip show zamba.

To update zamba to the most recent version if needed:

$ uv pip install -U zamba[video,image]

Operating systems that have been tested¶

macOS¶

zamba has been tested on macOS High Sierra.

Linux¶

zamba has been tested on Ubuntu regularly since 16.04. Tests run every week against the ubuntu-latest Github runner environment, so the version that Github uses is most likely to work. As of October 2023, that is 22.04.

Note, for Linux, you may need to install additional system packages to get zamba to work. For example, on Ubuntu, you may need to install build-essentials to have compilers.

FFMpeg 4, build-essentials, and some other packages that include more codecs to support additional videos and some other utilities can be installed with:

apt-get update && \
    apt-get install -y software-properties-common && \
    add-apt-repository -y ppa:savoury1/ffmpeg4 && \
    apt-get update && \
    apt-get -y install \
    build-essential \
    ffmpeg \
    git \
    libavcodec-dev \
    libavdevice-dev \
    libavfilter-dev \
    libavformat-dev \
    libavutil-dev \
    libsm6 \
    libswresample-dev \
    libswscale-dev \
    libxext6 \
    pkg-config \
    wget \
    x264 \
    x265

Windows¶

zamba works on Windows. The image extra installs without any additional tools. The video extra requires a C++ compiler because some dependencies (e.g. pycocotools) have native extensions.

Image workflows (no extra tools needed)¶

uv pip install zamba[image]

Video workflows¶

Install Visual Studio Build Tools — download the Build Tools for Visual Studio installer and select the "Desktop development with C++" workload. This provides the cl.exe compiler needed to build native extensions.
Install FFmpeg — use Chocolatey (choco install ffmpeg) or download from ffmpeg.org and add the bin folder to your system PATH.
Install zamba (we recommend uv):
```
uv pip install zamba[video]
```
Or with pip: pip install zamba[video].

Alternatively, you can use Docker or WSL to run zamba in a Linux environment on Windows.

Using GPU(s)¶

zamba is much faster on a machine with a graphics processing unit (GPU), but has also been developed and tested for machines without GPU(s).

To use a GPU, you must be using an NVIDIA GPU, have installed and configured CUDA, and have installed and configured CuDNN per their specifications.

If you are using conda, these dependencies can be installed through the cudatoolkit package. If using a GPU, you will also want to make sure that you install a compatible version of PyTorch with the version of CUDA you use. See the PyTorch installation docs for the easiest way to install the right version on your system.

Installing zamba¶

To install zamba¶