Install

Install

pip install libreyolo

# Comma-separate to combine several in one install.pip install "libreyolo[rfdetr,onnx]"

pip install "libreyolo[all]"

git clone https://github.com/LibreYOLO/libreyolo.gitcd libreyolopip install -e .

Python 3.10 or newer is required. The base install pulls PyTorch, torchvision, NumPy, Pillow, OpenCV, PyYAML, requests, mss, tqdm, pycocotools, typer, click, safetensors and SciPy, so YOLOv9 and the other families that need nothing more work straight after pip install libreyolo.

A clone checks out release, the stable branch whose code matches these docs. The integration branch, carrying unreleased work, is dev.

Optional extras

An extra is a bracketed name that adds the dependencies one model family or one export target needs. Nothing else changes: the API is the same whether or not an extra is present.

Model families

Export and runtimes

Training, evaluation and logging

fast-eval is opt-in rather than a hard dependency so that a platform without a prebuilt wheel cannot break a plain install. When the package is absent, COCO evaluation falls back to pycocotools and the run continues.

Tooling

Webcams, RTSP, RTMP, TCP, UDP, HLS and local multi-stream lists need no extra. Only YouTube page URLs do.

The aggregate extra

libreyolo[all] installs the model, export, tracking and logging extras in one command. Some are deliberately outside it. neptune is excluded because stable neptune-scale requires protobuf below 7 while the TFLite path requires protobuf 7. executorch is excluded because ExecuTorch constrains which PyTorch version it pairs with, and coreai because coreai-torch pins PyTorch to 2.11.x and would drag the whole environment onto that version. fast-eval, hub-kernels, clip-convert and siglip2-convert are also left out. Install any of them by name.

Platform constraints

Three extras are platform-scoped by their dependency markers, so the install succeeds everywhere and simply installs less where a wheel does not exist.

sensenova skips bitsandbytes on macOS, where no wheel is published; the rest of the extra installs normally.

If disk is the constraint, most of it is PyTorch, and most of PyTorch is the CUDA payload its default wheel bundles. A CPU-only wheel removes that without giving anything up. For ONNX detection on a machine that should carry no torch at all, see the lightweight install.

GPU and CUDA

Device selection happens when a model is constructed. The default, device="auto", uses CUDA when torch.cuda.is_available() is true, then Metal Performance Shaders when torch.backends.mps.is_available() is true, and CPU otherwise. Nothing else in the library inspects the hardware, so if PyTorch cannot see a GPU, neither can LibreYOLO.

To pin the device instead, pass device to the model or to predict, train, val and export. It accepts "cpu", "cuda", "cuda:0", "mps", a bare integer such as 0, or a digit string such as "0"; the last two are expanded to cuda:<n>.

Start with libreyolo checks, which prints the Torch version, the CUDA and cuDNN versions Torch was built against, and every visible GPU with its memory. When it reports no CUDA on a machine that has an NVIDIA card, the PyTorch wheel pip resolved is a CPU build. Install a CUDA build from the PyTorch index first, then install LibreYOLO:

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128pip install libreyolo

That is the same index the repository pins for its own uv-managed environment on Linux and Windows. It needs NVIDIA driver 555 or newer, which is the CUDA 12.8 runtime requirement. macOS keeps the PyPI wheel, since the PyTorch download host publishes no Darwin builds.

Check the install

# Python, Torch, CUDA, cuDNN, every visible GPU, and which# optional packages are installed.libreyolo checks

import libreyolo print(libreyolo.__version__)

# Every registered family with its tasks, sizes and input# resolutions. Families whose extra is missing are listed with# the pip command that enables them.libreyolo models

libreyolo models is the fastest way to see whether an extra took effect: a family whose dependency is missing is printed with the exact pip command that enables it. Both commands also accept --json, which prints the same data as a machine-readable object on stdout.