Skip to content

Installation Guide

This guide covers all methods of installing BoxLab, from simple pip installation to development setup.

Prerequisites

BoxLab requires Python 3.10 or higher. Check your Python version:

python --version
# or
python3 --version

Installation Methods

The simplest way to install BoxLab for end users:

pip install boxlab

Verify installation:

boxlab --version

Option 2: Install from Source

For the latest development version or to contribute:

  1. Install Poetry (if not already installed):
pip install pipx
pipx install poetry
  1. Clone the repository:
git clone https://github.com/6ixGODD/boxlab.git
cd boxlab
  1. Install dependencies:
# Basic installation
poetry install

# With development tools
poetry install --extras dev

# With testing tools
poetry install --extras test
  1. Activate the virtual environment:
poetry shell  # Need to install shell plugin. See https://python-poetry.org/docs/managing-environments/#activating-the-environment
  1. Verify installation:
poetry run python -m boxlab --version

Using pip

  1. Clone the repository:
git clone https://github.com/6ixGODD/boxlab.git
cd boxlab
  1. Install in editable mode:
# Basic installation
pip install -e .

# With development tools
pip install -e ".[dev]"

# With testing tools
pip install -e ".[test]"

# With all extras
pip install -e ".[dev,test]"
  1. Verify installation:
boxlab --version

Optional Dependencies

PyTorch Integration

For PyTorch integration and training workflows:

# Install PyTorch (CPU)
pip install torch torchvision

# Install PyTorch (GPU - CUDA 11.8)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

# Install PyTorch (GPU - CUDA 12.1)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

After installing PyTorch, you can use the PyTorch adapter:

from boxlab.dataset.torchadapter import build_torchdataset

GUI Dependencies

The annotator GUI requires additional packages (usually installed automatically):

pip install pillow matplotlib

Development Setup

For contributors and developers:

1. Install Development Tools

# Using Poetry
poetry install --extras dev

# Using pip
pip install -e ".[dev]"

This installs:

  • mkdocs - Documentation generation
  • mkdocs-material - Documentation theme
  • mkdocstrings - API documentation
  • pre-commit - Git hooks
  • ruff - Linting and formatting

2. Install Testing Tools

# Using Poetry
poetry install --extras test

# Using pip
pip install -e ".[test]"

This installs:

  • pytest - Testing framework
  • pytest-cov - Coverage reporting
  • mypy - Type checking
  • pylint - Code analysis

3. Setup Pre-commit Hooks

pre-commit install

4. Run Tests

# Using Poetry
poetry run pytest

# Using pip
pytest

# With coverage
pytest --cov=boxlab --cov-report=html

5. Build Documentation

# Using Poetry
poetry run mkdocs serve

# Using pip
mkdocs serve

Visit http://127.0.0.1:8000 to view documentation.

Running BoxLab

After installation, you can run BoxLab in multiple ways:

As a Command

boxlab --help

As a Python Module

python -m boxlab --help

In Python Scripts

from boxlab.dataset.io import load_dataset

dataset = load_dataset("path/to/dataset", format="coco")

Troubleshooting

Command Not Found

If boxlab command is not found after installation:

  1. Check if it's in PATH:
which boxlab
  1. Use full path (if installed with pip):
python -m boxlab --help
  1. Reinstall with pip:
pip uninstall boxlab
pip install boxlab

Import Errors

If you get import errors:

  1. Verify installation:
pip show boxlab
  1. Check Python version:
python --version
  1. Reinstall dependencies:
pip install --force-reinstall boxlab

Poetry Issues

If Poetry gives errors:

  1. Update Poetry:
poetry self update
  1. Clear cache:
poetry cache clear pypi --all
  1. Remove lock file and reinstall:
rm poetry.lock
poetry install

Upgrading

Upgrade from PyPI

pip install --upgrade boxlab

Upgrade from Source

cd boxlab
git pull
poetry install
# or
pip install -e .

Uninstallation

Uninstall with pip

pip uninstall boxlab

Uninstall with Poetry

# Remove virtual environment
poetry env remove python

# Or just uninstall
pip uninstall boxlab

System Requirements

Minimum Requirements

  • Python 3.10+
  • 2GB RAM
  • 500MB disk space
  • Python 3.11+
  • 4GB+ RAM
  • 1GB+ disk space
  • GPU (for PyTorch training)

Supported Platforms

  • Linux (Ubuntu 20.04+, Debian 10+, CentOS 7+)
  • macOS (10.15+)
  • Windows (10+)

Next Steps

Getting Help