Skip to content

Installation#

BehaviorScope-X requires Python 3.10 or newer. Python 3.11 is recommended for the broadest compatibility with the GUI and machine-learning dependencies.

Run the installation commands from the repository root—the directory containing pyproject.toml and requirements.txt.

Anaconda or Miniconda Environment#

This is the recommended installation path on Windows. It also works with Anaconda or Miniconda on Linux and macOS.

On Windows, open Anaconda Prompt. On Linux or macOS, open a terminal where conda has been initialized.

1. Get the repository#

Clone BehaviorScope-X and enter its directory:

git clone https://github.com/farhanaugustine/BehaviorScope-X.git
cd BehaviorScope-X

If you downloaded the repository as a ZIP file, extract it and use cd to enter the extracted BehaviorScope-X directory instead.

2. Create and activate the environment#

conda create --name behaviorscope-x python=3.11 pip -y
conda activate behaviorscope-x
python -m pip install --upgrade pip

The prompt should begin with (behaviorscope-x) after activation. Confirm that the active interpreter belongs to this environment:

python -c "import sys; print(sys.executable)"

Do not install BehaviorScope-X into Conda's base environment. Keeping it in a dedicated environment prevents unrelated scientific packages from changing its dependencies.

3. Choose CPU or GPU PyTorch#

For CPU-only use, continue directly to the next step. Installing BehaviorScope-X will install the default PyTorch build available for your platform.

For NVIDIA GPU training or inference, install the correct CUDA-enabled PyTorch build before installing BehaviorScope-X. Use the command generated by the official PyTorch installation selector for your operating system and supported CUDA version. For example, a selector command may look like:

python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126

The CUDA version in that URL is an example, not a requirement. Choose the build that matches the current PyTorch guidance and your NVIDIA driver.

4. Install BehaviorScope-X#

Install the repository in editable mode:

python -m pip install -e .

Editable installation keeps the command linked to this checkout and registers the behaviorscope-x launcher. Pulling or editing repository files does not require reinstalling the package unless its dependency or packaging metadata changes.

If you only want to install dependencies and launch the source script directly, this remains valid:

python -m pip install -r requirements.txt

Installing only requirements.txt does not register the behaviorscope-x terminal command.

5. Verify and launch#

Verify the main runtime packages:

python -c "import torch, PySide6, ultralytics; print('BehaviorScope-X dependencies are available'); print('CUDA available:', torch.cuda.is_available())"

Launch the installed application:

behaviorscope-x

You can always launch it from the repository source instead:

python behaviorscope_x_qt.py

Each new Anaconda Prompt or terminal session must reactivate the environment before launching the application:

conda activate behaviorscope-x
behaviorscope-x

Standard Python venv#

If you prefer a standard Python virtual environment, create it in the repository root.

python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -e .
behaviorscope-x

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
behaviorscope-x

For NVIDIA GPU use, install the CUDA-enabled PyTorch build after activating the environment and before running python -m pip install -e ..

System Dependencies#

Install ffmpeg if you plan to extract clips, convert videos, or write annotated review videos. BehaviorScope-X can read common MP4 files through OpenCV/Qt, but ffmpeg makes video handling more reliable.

Inside an activated Conda environment, one option is:

conda install --channel conda-forge ffmpeg

You can also install ffmpeg with your operating system's package manager and confirm that the ffmpeg command is available on PATH.

Model-Specific Dependencies#

YOLO-pose#

The YOLO-pose workflow requires:

  • ultralytics
  • a YOLO-pose .pt checkpoint trained for your animal, view, and keypoint layout
  • an NVIDIA GPU for practical training and faster cache building

MobileNetV3#

The MobileNetV3 workflow requires:

  • the MobileNetV3 pose-backbone checkpoint expected by the workflow runner
  • the shared controlled-comparison helper scripts included under analysis_workflows/shared_analysis_code
  • scikit-learn and xgboost for static-baseline training

DeepLabCut-HRNet#

The DeepLabCut-HRNet workflow requires:

  • a working DeepLabCut 3 environment
  • a DLC-format project with config.yaml
  • DLC SuperAnimal-compatible pose and detector checkpoints or a workflow configuration that can locate them
  • enough disk space for full-video NPZ caches and feature caches

Run DeepLabCut stages from the environment where deeplabcut imports successfully. The GUI can launch the Python runner, but the active interpreter must match the dependencies for the workflow being run. A dedicated DeepLabCut environment is usually safer than adding DeepLabCut to the main BehaviorScope-X environment.

Documentation Build#

Install the documentation-specific dependencies before serving or building the site:

python -m pip install -r requirements-docs.txt
mkdocs serve

Build the same strict site generated by GitHub Pages:

mkdocs build --strict