Skip to main content

Installation Guide

This guide will help you install all three packages in the WildDetect monorepo: WilData, WildTrain, and WildDetect.

Prerequisites​

System Requirements​

  • Python: 3.9, 3.10, or 3.11
  • Package Manager: uv (recommended) or pip
  • Git: For cloning repositories
  • GPU (optional): CUDA-capable GPU for faster inference and training

Operating System​

  • Windows 10/11
  • Linux (Ubuntu 20.04+ recommended)
  • macOS (Intel or Apple Silicon)

!!! note "Windows Users" This monorepo is developed and tested on Windows. All scripts use .bat format for Windows compatibility.

Installation Methods​

=== "Method 1: Install from Source (Recommended)"

1. Clone the Repository​

git clone https://github.com/fadelmamar/wildetect.git
cd wildetect

2. Create Virtual Environment​

Using uv (recommended):

uv venv --python 3.11

# Activate on Windows
.venv\Scripts\activate

# Activate on Linux/macOS
source .venv/bin/activate

3. Install PyTorch (GPU or CPU)​

With CUDA 11.8 (GPU):

uv pip install torch==2.6.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

CPU Only:

uv pip install torch==2.6.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

4. Install WildDetect Packages​

Install all three packages in development mode:

# Install WilData
cd wildata
uv pip install -e .
cd ..

# Install WildTrain
cd wildtrain
uv pip install -e .
cd ..

# Install WildDetect (main package)
uv pip install -e .

5. Install MMDetection (Optional)​

If you want to use MMDetection framework:

# Install OpenMMLab dependencies
uv pip install -U openmim
uv run mim install mmengine

# Install MMCV (choose based on your setup)
# For CPU:
uv pip install mmcv==2.0.1 -f https://download.openmmlab.com/mmcv/dist/cpu/torch2.1/index.html

# For CUDA 11.8:
uv pip install mmcv==2.0.1 -f https://download.openmmlab.com/mmcv/dist/cu118/torch2.1/index.html

# Install MMDetection
uv run mim install mmdet
uv pip install numpy==1.26.4

=== "Method 2: Install from GitHub"

You can install packages directly from GitHub:

# Install WilData
uv pip install git+https://github.com/fadelmamar/wildata

# Install WildTrain
uv pip install git+https://github.com/fadelmamar/wildtrain

# Install WildDetect
uv pip install git+https://github.com/fadelmamar/wildetect

=== "Method 3: Using uv sync"

If packages have uv.lock files:

# In each package directory
cd wildata
uv sync

cd ../wildtrain
uv sync

cd ../
uv sync

Verification​

Verify your installation by checking package versions:

# Check WilData
wildata --version

# Check WildTrain  
wildtrain --version

# Check WildDetect
wildetect --version

Optional Dependencies​

DVC (Data Version Control)​

For dataset versioning with WilData:

# Basic DVC
uv pip install "wildata[dvc]"

# With cloud storage support
uv pip install "dvc[s3]"      # AWS S3
uv pip install "dvc[gcs]"     # Google Cloud Storage
uv pip install "dvc[azure]"   # Azure Blob Storage

Label Studio Integration​

For working with Label Studio annotations:

uv pip install label-studio-sdk

FiftyOne Visualization​

For interactive dataset visualization:

uv pip install fiftyone

GPU Setup​

CUDA Configuration​

If you have an NVIDIA GPU, ensure CUDA is properly installed:

  1. Check CUDA availability:

    python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"
    python -c "import torch; print(f'CUDA Version: {torch.version.cuda}')"

  2. Check GPU devices:

    python -c "import torch; print(f'GPU Count: {torch.cuda.device_count()}')"
    python -c "import torch; print(f'GPU Name: {torch.cuda.get_device_name(0)}')"

Memory Requirements​

TaskMinimum RAMRecommended RAMGPU Memory
Detection8GB16GB4GB
Training16GB32GB8GB
Large Rasters32GB64GB8GB+

Troubleshooting​

Common Issues​

??? question "Import errors after installation"

Make sure your virtual environment is activated:

# Windows
.venv\Scripts\activate

# Linux/macOS
source .venv/bin/activate

??? question "CUDA out of memory"

Reduce batch size or tile size in your configuration files:

processing:
  batch_size: 16  # Reduce from 32
  tile_size: 640  # Reduce from 800

??? question "MMDetection installation fails"

Install dependencies in this order:

  1. PyTorch
  2. MMCV (matching your CUDA version)
  3. MMEngine
  4. MMDetection

??? question "uv command not found"

Install uv package manager:

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows-Specific Issues​

!!! warning "ProcessPool Not Supported" On Windows, multiprocessing with ProcessPoolExecutor is not supported. The packages automatically use threading instead.

Getting Help​

If you encounter issues:

  1. Check the Troubleshooting Guide
  2. Search GitHub Issues
  3. Create a new issue with your error message and system info

Next Steps​

Once installation is complete:

  1. 📚 Set up your environment
  2. 🚀 Follow the Quick Start guide
  3. 📖 Explore tutorials

Installation successful? Head to the Environment Setup to configure your workspace.