Instalação

Instalação

pip install libreyolo

# Separe por vírgulas para combinar vários em uma só instalação.pip install "libreyolo[rfdetr,onnx]"

pip install "libreyolo[all]"

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

É necessário Python 3.10 ou superior. A instalação base traz PyTorch, torchvision, NumPy, Pillow, OpenCV, PyYAML, requests, mss, tqdm, pycocotools, typer, click, safetensors e SciPy, então o YOLOv9 e as demais famílias que não precisam de mais nada funcionam logo após pip install libreyolo.

Um clone faz checkout de release, o branch estável cujo código corresponde a esta documentação. O branch de integração, que carrega o trabalho ainda não lançado, é dev.

Extras opcionais

Um extra é um nome entre colchetes que adiciona as dependências de que uma família de modelos ou um destino de exportação precisa. Nada mais muda: a API é a mesma com ou sem o extra.

Famílias de modelos

Exportação e runtimes

Treinamento, avaliação e logging

fast-eval é opcional em vez de dependência obrigatória para que uma plataforma sem wheel pré-compilada não quebre uma instalação simples. Quando o pacote está ausente, a avaliação COCO recorre ao pycocotools e a execução continua.

Ferramentas

Webcams, RTSP, RTMP, TCP, UDP, HLS e listas locais de múltiplos streams não precisam de extra. Só as URLs de páginas do YouTube precisam.

O extra agregado

libreyolo[all] instala os extras de modelos, exportação, tracking e logging em um único comando. Alguns ficam deliberadamente de fora. neptune é excluído porque o neptune-scale estável exige protobuf abaixo de 7, enquanto o caminho do TFLite exige protobuf 7. executorch é excluído porque o ExecuTorch limita com qual versão do PyTorch ele se combina, e coreai porque coreai-torch fixa o PyTorch em 2.11.x e arrastaria todo o ambiente para essa versão. fast-eval, hub-kernels, clip-convert e siglip2-convert também ficam de fora. Instale qualquer um deles pelo nome.

Restrições de plataforma

Três extras são delimitados por plataforma pelos seus marcadores de dependência, então a instalação funciona em todo lugar e simplesmente instala menos onde não existe wheel.

sensenova pula bitsandbytes no macOS, onde nenhuma wheel é publicada; o resto do extra instala normalmente.

Se a restrição for o disco, a maior parte dele é o PyTorch, e a maior parte do PyTorch é a carga CUDA que a wheel padrão embute. Uma wheel só de CPU remove isso sem abrir mão de nada. Para detecção com ONNX em uma máquina que não deve carregar torch nenhum, veja a instalação leve.

GPU e CUDA

A seleção de dispositivo acontece quando o modelo é construído. O padrão, device="auto", usa CUDA quando torch.cuda.is_available() é verdadeiro, depois Metal Performance Shaders quando torch.backends.mps.is_available() é verdadeiro, e CPU caso contrário. Nada mais na biblioteca inspeciona o hardware, então, se o PyTorch não enxerga uma GPU, o LibreYOLO também não.

Para fixar o dispositivo, passe device ao modelo ou a predict, train, val e export. Ele aceita "cpu", "cuda", "cuda:0", "mps", um inteiro puro como 0, ou uma string de dígito como "0"; os dois últimos são expandidos para cuda:<n>.

Comece por libreyolo checks, que imprime a versão do Torch, as versões de CUDA e cuDNN contra as quais o Torch foi compilado, e cada GPU visível com sua memória. Quando ele informa que não há CUDA em uma máquina que tem placa NVIDIA, a wheel do PyTorch que o pip resolveu é uma build de CPU. Instale uma build com CUDA a partir do índice do PyTorch primeiro e só então instale o LibreYOLO:

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

Esse é o mesmo índice que o repositório fixa para o próprio ambiente gerenciado por uv no Linux e no Windows. Ele precisa do driver NVIDIA 555 ou superior, que é o requisito do runtime CUDA 12.8. O macOS fica com a wheel do PyPI, já que o host de download do PyTorch não publica builds para Darwin.

Conferir a instalação

# Python, Torch, CUDA, cuDNN, cada GPU visível e quais# pacotes opcionais estão instalados.libreyolo checks

import libreyolo print(libreyolo.__version__)

# Cada família registrada com suas tarefas, tamanhos e# resoluções de entrada. Famílias cujo extra está faltando são# listadas com o comando pip que as habilita.libreyolo models

libreyolo models é a forma mais rápida de ver se um extra fez efeito: uma família cuja dependência está faltando é impressa com o comando pip exato que a habilita. Os dois comandos também aceitam --json, que imprime os mesmos dados como um objeto legível por máquina no stdout.