Skip to content

Installation

Welcome to RF-DETR! This guide will help you install and set up RF-DETR for your projects. Whether you're a developer looking to contribute or an end-user ready to start using RF-DETR, we've got you covered.

Installation Methods

RF-DETR supports several installation methods. Choose the option which best fits your workflow.

Installation

The easiest way to install RF-DETR is using pip. This method is recommended for most users.

pip install rfdetr

If you are using uv, you can install RF-DETR using the following command:

uv pip install rfdetr

For uv projects, you can also use:

uv add rfdetr

To install the latest development version of RF-DETR from source without cloning the full repository, run the command below.

pip install https://github.com/roboflow/rf-detr/archive/refs/heads/develop.zip

Dev Environment

If you plan to contribute to RF-DETR or modify the codebase locally, set up a local development environment using the steps below.

Development Setup

# Clone the repository and navigate to the root directory
git clone --depth 1 -b develop https://github.com/roboflow/rf-detr.git
cd rf-detr

# Set up a Python virtual environment with a specific Python version (e.g., 3.10)
python3.10 -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install the package in development mode
pip install -e "."

# Clone the repository and navigate to the root directory
git clone --depth 1 -b develop https://github.com/roboflow/rf-detr.git
cd rf-detr

# Pin Python version (optional but recommended)
uv python pin 3.11

# Sync environment (creates .venv, installs pinned Python, and installs dependencies)
uv sync

# Install the package in development mode with all extras
uv pip install -e . --all-extras

Optional Extras

RF-DETR provides several optional extras for additional functionality:

Extra Install command Purpose
train pip install "rfdetr[train]" Training dependencies (PyTorch Lightning, etc.)
loggers pip install "rfdetr[loggers]" Experiment tracking (TensorBoard, W&B, MLflow, ClearML)
onnx pip install "rfdetr[onnx]" ONNX export
tflite pip install "rfdetr[tflite]" TFLite export (Python 3.12 only)
executorch pip install "rfdetr[executorch]" ExecuTorch export (.pte)
coreml pip install "rfdetr[coreml]" Native CoreML export (.mlpackage; macOS only)
tensorrt pip install "rfdetr[tensorrt]" TensorRT inference (pycuda, onnxruntime-gpu, tensorrt)
augment pip install "rfdetr[augment]" Custom CPU (Albumentations) + GPU (Kornia) augmentations
lora pip install "rfdetr[lora]" LoRA fine-tuning with PEFT
visual pip install "rfdetr[visual]" Visualization utilities (matplotlib, pandas, seaborn)
cli pip install "rfdetr[cli]" CLI with typed argument parsing (jsonargparse)
plus pip install "rfdetr[plus]" XLarge and 2XLarge detection models (PML 1.0 license)

Additional Notes

  • Ensure you have Python 3.10 or higher installed.
  • For development, it is recommended to use a virtual environment to avoid conflicts with other packages.
  • Augmentation extras:
    • Training uses torchvision-native default augmentations with pip install "rfdetr[train]".
    • Custom Albumentations CPU configs and Kornia GPU augmentation both require pip install "rfdetr[train,augment]".
  • If you encounter any issues during installation, refer to the troubleshooting section or open an issue on the GitHub repository.

Troubleshooting

If you encounter any issues during installation, here are some common solutions:

  • Permission Issues: Use pip install --user rfdetr to install the package for your user only.
  • Dependency Conflicts: Use a virtual environment to isolate the installation.
  • Python Version: Ensure you are using Python 3.10 or higher.