Install & Compatibility
Where this runs
tested against v0.4.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
py 3.10
✕ build_error
✓ 83.2s
py 3.11
✕ build_error
✓ 78.6s
py 3.12
✕ build_error
✓ 67.4s
py 3.13
✕ build_error
✓ 61.5s
py 3.9
✕ build_error
✕ timeout
4890MB installed
● package 4890MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_model
✓ from effdet import create_model
✗ from effdet import EfficientDet, DetBenchTrain
The `create_model` function is the recommended high-level API for instantiating models, including loading pretrained weights. Direct import of `EfficientDet` and `DetBenchTrain` is less common for typical usage and mostly for advanced customization.
This quickstart demonstrates how to load a pre-trained EfficientDet model, prepare a dummy image, and perform inference to detect objects. It utilizes the high-level `create_model` function and standard PyTorch image transformations.
import torch
from effdet import create_model
from effdet.data import resolve_input_config
from torchvision import transforms
from PIL import Image
import os
# Create a dummy image for a runnable example
dummy_image_path = "dummy_image.png"
if not os.path.exists(dummy_image_path):
img = Image.new('RGB', (640, 640), color = 'red')
img.save(dummy_image_path)
# 1. Load a pre-trained EfficientDet model
# Use 'tf_efficientdet_d0' for a small, fast model.
# bench_task='predict' is crucial for inference mode.
model_name = 'tf_efficientdet_d0'
model = create_model(model_name, pretrained=True, bench_task='predict')
model.eval()
# 2. Prepare the image for inference
img = Image.open(dummy_image_path).convert('RGB')
# Resolve input configuration from the model's pretrained_cfg
input_config = resolve_input_config(model.pretrained_cfg)
# Define image transformation pipeline
transform = transforms.Compose([
transforms.Resize(input_config['input_size']),
transforms.ToTensor(),
transforms.Normalize(mean=input_config['mean'], std=input_config['std'])
])
# Apply transformations and add a batch dimension
input_tensor = transform(img).unsqueeze(0)
# 3. Perform inference
with torch.no_grad():
output = model(input_tensor)
# The output format is typically [x1, y1, x2, y2, score, class]
# Print top 5 detected objects (if any)
if output.numel() > 0:
print(f"Detected objects (top 5, if available):\n{output[0][:5]}")
else:
print("No objects detected.")
# Clean up dummy image
os.remove(dummy_image_path)
Debug
Known issues
breakingThe bounding box output format for 'Predict' and 'Train' benches changed from `XYWH` (x, y, width, height) to `XYXY` (x1, y1, x2, y2). Users upgrading from older versions or following outdated tutorials must adjust their parsing logic.fixUpdate your code to expect `XYXY` format for bounding boxes. This format is `[x_min, y_min, x_max, y_max]`.
affects: <=0.2.x to >=0.2.4 (and current)
breaking`effdet` has tight dependencies on `timm` (PyTorch Image Models) versions. Upgrading `effdet` often requires updating `timm` to a specific version (e.g., `>=0.3` or `>=0.9`) due to API changes in `timm`'s helper functions and model backbones.fixEnsure your `timm` installation matches the requirements of your `effdet` version. Check `effdet`'s `requirements.txt` or GitHub README for the exact `timm` version compatibility.
affects: All versions, specifically when upgrading `effdet` or `timm` independently.
gotchaInput image dimensions must be divisible by 128 due to the EfficientDet's BiFPN (Bi-directional Feature Pyramid Network) architecture, which processes features at various scales (P3 to P7).fixWhen resizing input images, ensure both width and height are multiples of 128 (e.g., 512x512, 640x640, 768x768). Non-compliant sizes might lead to errors or unexpected behavior.
affects: All versions
deprecatedThe default focal loss implementation changed. The older version, which might have more numerical stability issues but potentially lower memory usage, can be explicitly enabled during training.fixIf reproducing old results or encountering training issues, use the `--legacy-focal` argument in training scripts to revert to the previous focal loss implementation. Otherwise, the new focal loss is used by default.
affects: >=0.2.4 (since its introduction around 2020-12-07 update)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'effdet'
The `effdet` library or its submodules are not correctly installed or not accessible in the Python environment. This often occurs when installing directly from a local clone or an older method.
fixEnsure `effdet` is installed from the official GitHub repository, typically with an editable install: `pip install -e "git+https://github.com/rwightman/efficientdet-pytorch.git#egg=effdet"` or `pip install effdet` if using a PyPI version, then restart your environment (e.g., Jupyter kernel).
TypeError: forward() takes 3 positional arguments but 4 were given
This error often arises from a mismatch between the `effdet` version and its `timm` dependency, or changes in the `forward` method signature of `DetBenchTrain` or `EfficientDet` between different versions, especially when handling inputs like images, boxes, and labels during training.
fixThis is frequently due to API changes in `effdet` or `timm`. The common fix involves adjusting how the model's `forward` method is called. For example, some versions expect `output = self.model(images, targets)` instead of `loss, _, _ = self.model(images, boxes, labels)`. Check the `effdet` version's specific examples or GitHub issues for the correct `forward` call signature.
RuntimeError: CUDA out of memory. Tried to allocate X MiB (GPU Y; Z GiB total capacity; A GiB already allocated; B MiB free; C KiB cached)
The GPU lacks sufficient memory to perform the requested operation, typically during model training or inference with large batch sizes, high-resolution images, or extensive model parameters.
fixReduce the `batch_size`, decrease the input `image_size`, use mixed-precision training (e.g., `torch.cuda.amp.autocast`), or free up GPU memory by deleting unnecessary tensors and calling `torch.cuda.empty_cache()`.
RuntimeError: Sizes of tensors must match except in dimension X. Expected size Y but got size Z for tensor number W in the list.
This error occurs when concatenating or performing operations on tensors that are expected to have matching dimensions (except for a specific batch or sequence dimension), but their sizes are incompatible. This is common in data loading, augmentation, or when model components expect specific input shapes.
fixCarefully inspect the shapes of the tensors involved in the operation. Ensure that data preprocessing, augmentation, and model input transformations consistently produce tensors of compatible dimensions. This often involves debugging the dataset's `__getitem__` or `collate_fn` to ensure bounding box and label tensors match the expected format for `effdet`'s anchor generation and loss calculation.
TypeError: 'FeatureInfo' object is not callable
This specific error happens when an `EfficientDet` model initialization attempts to call `self.backbone.feature_info()` as a method, but in certain versions or configurations, `feature_info` is a property (attribute) and not a callable function, leading to a `TypeError`.
fixModify the code to access `feature_info` as an attribute instead of calling it as a method. For example, change `self.backbone.feature_info()` to `self.backbone.feature_info`.
Upgrade
Version history
0.4.1latest on PyPI · released May 21, 2023
Audit
Dependencies
torchrequiredCore PyTorch deep learning framework.
torchvisionrequiredStandard library for computer vision tasks in PyTorch.
timmrequiredPyTorch Image Models, provides backbones (e.g., EfficientNet) and various utilities. A key dependency for effdet models.
pycocotoolsrequiredUsed for COCO dataset evaluation and utilities.
omegaconfrequiredUsed for managing model configurations.