Install & Compatibility
Where this runs
tested against v0.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
1138MB installed
● package 1138MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RFDETRSmall
✓ from rfdetr import RFDETRSmall
RFDETRBase
✓ from rfdetr import RFDETRBase
RFDETRLarge
✓ from rfdetr import RFDETRLarge
DetectionDataset
✓ from rfdetr.data import DetectionDataset
✗ from rfdetr.datasets import DetectionDataset
Dataset classes were refactored into the `rfdetr.data` module.
This quickstart demonstrates how to load a pre-trained RF-DETR model, perform inference on an image URL, and inspect the returned detections object. It highlights recently added data fields like class names and source image/shape, which are useful for post-processing and visualization with libraries like `supervision`.
import supervision as sv
from rfdetr import RFDETRSmall
# Initialize model with pre-trained weights. Use "rfdetr-small" for the default.
# For a custom fine-tuned model: pretrain_weights="path/to/your/model.pth"
model = RFDETRSmall(pretrain_weights="rfdetr-small")
# Example image URL for prediction
image_url = "https://media.roboflow.com/dog.jpg"
# Perform inference with a confidence threshold
detections = model.predict(image_url, threshold=0.5)
print(f"Detected {len(detections)} objects.")
# Access new data points introduced in recent versions:
if "class_name" in detections.data:
print(f"Class names: {detections.data['class_name']}")
if "source_image" in detections.data:
print(f"Source image shape: {detections.data['source_shape']}")
# Visualize results (requires 'supervision' to be installed)
# image_bgr = detections.data.get("source_image")
# if image_bgr is not None:
# box_annotator = sv.BoxAnnotator()
# annotated_image = box_annotator.annotate(scene=image_bgr.copy(), detections=detections)
# sv.plot_image(annotated_image, size=(8, 8))
Errors
Common errors & fixes
ImportError: rfdetr[train] is not installed. Please install with 'pip install "rfdetr[train]"'
Attempting to use training-specific modules or functions without installing the optional training dependencies.
fixInstall `rfdetr` with its training dependencies: `pip install "rfdetr[train]"`
KeyError: 'class_name'
Attempting to access `detections.data['class_name']` using an `rfdetr` version older than 1.6.4, where this key was not present.
fixUpgrade `rfdetr` to `v1.6.4` or later, or use `detections.data.get('class_name')` and handle `None` for backward compatibility. ValueError: Input shape dimensions must be divisible by 14. Got (500, 500)
The `shape` argument passed to `RFDETR.predict()` had dimensions (height, width) that were not perfectly divisible by 14.
fixProvide a `shape` where both height and width are positive integers divisible by 14, e.g., `model.predict(..., shape=(480, 640))`.
TypeError: RFDETR.export() got an unexpected keyword argument 'simplify'
Using the deprecated `simplify` or `force` arguments in `RFDETR.export()`, which are no longer supported since v1.6.1.
fixRemove the `simplify` and `force` arguments from your `RFDETR.export()` method calls.
Upgrade
Version history
1.8.0latest on PyPI · released Jun 16, 2026
Audit
Dependencies
torchrequiredUnderlying deep learning framework.
torchvisionrequiredStandard computer vision library for PyTorch.
supervisionoptionalRecommended for easy visualization and annotation of results.
lightningoptionalRequired for training functionality (included in `rfdetr[train]`).