Lightweight install

Why this works

pip install --no-deps libreyolo installs the package and skips its dependency list entirely. Nothing is resolved on your behalf, and you become responsible for installing what you actually use.

That is only useful if the code path you want genuinely does not need the dependencies you skipped, and for ONNX detection it does not. The decode, including non-maximum suppression, is numpy. The preprocessing recipes are numpy. PyTorch is a training and eager-inference dependency, and on this path it is never called.

Before this release the import failed anyway: importing anything under libreyolo.models built every model class to populate the checkpoint auto-detection registry, and those classes are torch.nn.Module subclasses. The preprocessing recipes now live in their own package and the torch import is deferred until something touches a torch attribute, so the ONNX path imports with torch absent from the machine.

Try the CPU-only wheel first

Most people asking for this want to avoid a multi-gigabyte install, and the size is concentrated in one place: the default torch wheel bundles CUDA. A CPU-only build is a fraction of that and needs no special install path.

# Install the package without its dependency list, then supply the# four packages the ONNX detection path actually imports.pip install --no-deps libreyolopip install numpy pillow opencv-python-headless onnxruntime

# Try this first. It keeps every feature and avoids the CUDA wheel,# which is where most of the disk goes.pip install libreyolo --index-url https://download.pytorch.org/whl/cpu

The CPU-only option keeps every LibreYOLO feature: training, validation, every task, every family, the CLI. Take the lightweight path when you want zero torch on the machine, not merely less of it.

What the lightweight install covers

Seven families were verified on this path: YOLOv9, YOLO-NAS, EdgeCrafter, RT-DETR, RF-DETR, D-FINE and DEIM, counting each family's variants with it.

That is the verified scope, not a boundary the library enforces. Other tasks and other families are simply outside what was checked: some will pull torch when you call them, and a few may happen to work. Treat anything beyond this list as untested rather than as supported or as broken.

Inside it, results are identical to the normal install, not merely close. Each family was exported to ONNX and run twice, once normally and once with torch blocked; boxes, scores and classes matched exactly. A parity test in the suite keeps that contract from drifting.

The five things that catch people

Use OnnxBackend, not the model classes. LibreYOLO9("model.onnx") still requires torch, because LibreYOLO9 is itself an nn.Module subclass. This is the likeliest mistake, since every other page in these docs loads a model through its class or through LibreYOLO().

Export somewhere else. Producing the .onnx file requires torch, so the lightweight machine cannot make one. Export on a development or CI machine and ship the artifact to the slim target.

Results carry numpy arrays. result.boxes.xyxy is an ndarray here. The containers accept either type so the attribute names are unchanged, but code that calls .cpu() or .numpy() on a result will fail.

A single image returns a single Results. predict() returns one Results for one image and a list for several. Indexing a single result with [0] selects the first detection, not the first image, which silently gives you a one-box result instead of raising.

The CLI will not work. typer and click are not in the four packages, so the libreyolo command is unavailable. This is a library install.

Predict

from libreyolo.backends.onnx import OnnxBackend model = OnnxBackend("libreyolo9t.onnx")result = model.predict("https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg") # xyxy is a numpy ndarray here, not a torch tensor.print(result.boxes.xyxy)print(result.boxes.conf)print(result.boxes.cls)

Swap onnxruntime for onnxruntime-gpu to run on CUDA. The four packages are the ones a full torch-free predict() actually imports, recorded during the call rather than reasoned about. opencv-python-headless stands in for the declared opencv-python: same module, no GUI libraries, smaller on disk.

Of the remaining declared dependencies, requests is needed only to load an image from a URL, pycocotools and scipy are validation and evaluation, and typer and click are the CLI.

This list will drift, by design

The package list above is correct for the release named at the top of this page. --no-deps opts you out of dependency resolution, so nothing checks it for you, and a later release may import something not listed here.

If you hit a ModuleNotFoundError, you already understand the technique: install the missing package. That is the intended maintenance model rather than a bug report. This path is best effort and is not a separately supported distribution, which is also why there is no second lightweight package on PyPI and no plan for one.

To confirm your environment is really torch-free rather than quietly falling back to an installed copy, assert it:

import importlib.util assert importlib.util.find_spec("torch") is None, "torch is installed"

That check is worth keeping in CI for the slim image. Without it, an environment that happens to have torch will pass every test and tell you nothing.