roboflow--rf-detr/docs/getting-started/migration.md

description

description
Per-version migration guide for RF-DETR. Covers breaking changes and deprecated APIs for each release series.

Migration Guide

Read each section between your current version and your target — every section covers only the delta between two adjacent releases.

1.4.x  →  1.5 →  1.6  →  1.7  →  1.8

You can apply all changes in one go; working through sections one release at a time and verifying between each step is optional but makes failures easier to isolate. Deprecated APIs emit a DeprecationWarning until the version marked for removal. See the Changelog for the full list of changes in each release.

---

Upgrade 1.8 → 1.9

Planned for Removal in v1.9

The following APIs were deprecated in earlier releases and will be removed in v1.9. They still work in the current release (v1.8.x) but emit DeprecationWarning. Update your code before upgrading.

!!! warning "Planned for removal: rfdetr.util.* and rfdetr.deploy.* import paths"

Deprecated since v1.6. Use the canonical replacements listed in the [Upgrade 1.5 → 1.6](#upgrade-15--16) section.

```python
# These imports still work in v1.8 but emit DeprecationWarning; update before v1.9
from rfdetr.util.coco_classes import COCO_CLASSES  # → rfdetr.assets.coco_classes
from rfdetr.util.misc import get_rank  # → rfdetr.utilities
from rfdetr.deploy import export_onnx  # → rfdetr.export.main
```

!!! warning "Planned for removal: build_namespace(model_config, train_config)"

Deprecated since v1.7. Use `build_model_from_config` and `build_criterion_from_config` instead.

!!! warning "Planned for removal: load_pretrain_weights(nn_model, model_config, train_config) with train_config"

Deprecated since v1.7. Drop the `train_config` positional argument.

!!! warning "Planned for removal: start_epoch kwarg in train()"

Deprecated since v1.7. PyTorch Lightning resumes automatically via `resume=`.

!!! warning "Planned for removal: do_benchmark kwarg in train()"

Deprecated since v1.7. Use the `rfdetr.export.benchmark` module instead.

!!! warning "Planned for removal: callbacks dict kwarg in train()"

Deprecated since v1.7. Pass PTL `Callback` objects directly via the Lightning API instead.

!!! warning "Planned for removal: misplaced config fields"

The following `TrainConfig` and `ModelConfig` fields moved to their correct config class in v1.7 and the deprecated compatibility shims will be removed in v1.9. Update any direct references:

| Field               | Removed from  | Use in        |
| ------------------- | ------------- | ------------- |
| `group_detr`        | `TrainConfig` | `ModelConfig` |
| `ia_bce_loss`       | `TrainConfig` | `ModelConfig` |
| `segmentation_head` | `TrainConfig` | `ModelConfig` |
| `num_select`        | `TrainConfig` | `ModelConfig` |
| `cls_loss_coef`     | `ModelConfig` | `TrainConfig` |

---

Upgrade 1.7 → 1.8

Breaking changes

!!! note "Breaking in v1.8.2: default keypoint schema changed to active-first [17]"

New checkpoints created from v1.8.2 onwards use `class_id=0` for person. Legacy `[0, 17]` checkpoints
are still supported — RF-DETR auto-detects the schema from the checkpoint at load time.

If your post-processing code offsets class IDs by 1 (common for background-first models), update it:

```python
# Before (background-first [0, 17]: person was at class_id=1)
class_name = "person" if detection.class_id == 1 else "other"

# After (active-first [17]: person is at class_id=0)
class_name = "person" if detection.class_id == 0 else "other"
```

Use `detection.data["class_name"]` for schema-agnostic name resolution.

!!! warning "Breaking: rfdetr.datasets.aug_config renamed to rfdetr.datasets.aug_configs"

The augmentation config module was renamed (singular → plural). If you import from it directly:

```python
# Before
from rfdetr.datasets.aug_config import AUG_AGGRESSIVE

# After
from rfdetr.datasets.aug_configs import AUG_AGGRESSIVE
```

All preset constants (`AUG_AGGRESSIVE`, `AUG_CONSERVATIVE`, etc.) are unchanged.

!!! warning "Breaking: supervision>=0.29.0 now required"

Required for `sv.KeyPoints` support. `pip install rfdetr==1.8.0` pulls this automatically.
If another dependency pins `supervision<0.29.0`, resolve the conflict manually.

!!! warning "Breaking: pyDeprecate constraint narrowed to >=0.9,<0.10"

Was `>=0.6,<0.8`. If another package pins an older version, resolve with:

```bash
pip install "rfdetr==1.8.0" "pyDeprecate>=0.9,<0.10"
```

---

Upgrade 1.6 → 1.7

Breaking changes

!!! warning "Breaking: peft removed from the default install"

LoRA fine-tuning now requires the `lora` extra. If you use LoRA adapters during
training, update your install command.

```bash
# Before
pip install rfdetr

# After
pip install 'rfdetr[lora]'
```

!!! warning "Breaking: predict() stores source image in detections.metadata"

**`predict()` stores the source image in `detections.metadata`, not `detections.data`.**

```python
# Before (1.6.4 and earlier)
source = detections.data["source_image"]

# After
source = detections.metadata["source_image"]
```

!!! warning "Breaking: pyDeprecate constraint changed to >=0.6,<0.8"

Was `>=0.3,<0.6`. If another package pins an older version, resolve with:

```bash
pip install "rfdetr==1.7.0" "pyDeprecate>=0.6,<0.8"
```

Deprecated in v1.7 → Remove in v1.9

!!! note "Deprecated: build_namespace() split into two functions"

**`build_namespace(model_config, train_config)`** — use `build_model_from_config` or
`build_criterion_from_config` instead.

```python
# Before (deprecated)
from rfdetr.models import build_namespace

ns = build_namespace(model_config, train_config)

# After
from rfdetr.models import build_model_from_config, build_criterion_from_config

model = build_model_from_config(model_config)
criterion = build_criterion_from_config(model_config, train_config)
```

!!! note "Deprecated: load_pretrain_weights() no longer takes train_config"

**`load_pretrain_weights(nn_model, model_config, train_config)`** — drop the
`train_config` positional argument.

```python
# Before (deprecated)
from rfdetr.models import load_pretrain_weights

load_pretrain_weights(nn_model, model_config, train_config)

# After
from rfdetr.models import load_pretrain_weights

load_pretrain_weights(nn_model, model_config)
```

!!! note "Deprecated: config fields moved between ModelConfig and TrainConfig"

**Config fields placed in the wrong config object.** Move them as shown:

| Field               | Was in        | Move to       |
| ------------------- | ------------- | ------------- |
| `group_detr`        | `TrainConfig` | `ModelConfig` |
| `ia_bce_loss`       | `TrainConfig` | `ModelConfig` |
| `segmentation_head` | `TrainConfig` | `ModelConfig` |
| `num_select`        | `TrainConfig` | `ModelConfig` |
| `cls_loss_coef`     | `ModelConfig` | `TrainConfig` |

```python
# Before (deprecated)
train_config = TrainConfig(group_detr=13, cls_loss_coef=2.0)

# After
model_config = ModelConfig(group_detr=13)
train_config = TrainConfig(cls_loss_coef=2.0)
```

Deprecated in v1.7 → Remove in v2.0

!!! note "Deprecated: RFDETRBase replaced by size-specific classes"

**`RFDETRBase`** defaulted to the small variant and is replaced by size-specific
classes. Choose the variant that matches your previous model size. If you used
`RFDETRBase()` without arguments, switch to `RFDETRSmall()`.

```python
# Before (deprecated)
from rfdetr import RFDETRBase

model = RFDETRBase()

# After — pick one
from rfdetr import RFDETRNano, RFDETRSmall, RFDETRMedium, RFDETRLarge

model = RFDETRSmall()
```

!!! note "Deprecated: RFDETRSegPreview replaced by size-specific segmentation classes"

**`RFDETRSegPreview`** defaulted to the small variant and is replaced by size-specific
segmentation classes. If you used `RFDETRSegPreview()` without arguments, switch to
`RFDETRSegSmall()`.

```python
# Before (deprecated)
from rfdetr import RFDETRSegPreview

model = RFDETRSegPreview()

# After — pick one
from rfdetr import RFDETRSegNano, RFDETRSegSmall, RFDETRSegMedium, RFDETRSegLarge

model = RFDETRSegSmall()
```

---

Upgrade 1.5 → 1.6

Breaking changes

!!! warning "Breaking: transformers minimum version raised to >=5.1.0"

**`transformers` minimum version raised to `>=5.1.0,<6.0.0`.**

Projects pinned to `transformers<5.0.0` must upgrade. If upgrading is not possible,
pin `rfdetr<1.6.0`.

```bash
pip install 'transformers>=5.1.0,<6.0.0'
```

!!! warning "Breaking: PyPI extras renamed"

**PyPI extras renamed.**

Update your `pip install` commands and `requirements*.txt` files.

| Old extra            | New extra         |
| -------------------- | ----------------- |
| `rfdetr[metrics]`    | `rfdetr[loggers]` |
| `rfdetr[onnxexport]` | `rfdetr[onnx]`    |

```bash
# Before
pip install 'rfdetr[metrics]'
pip install 'rfdetr[onnxexport]'

# After
pip install 'rfdetr[loggers]'
pip install 'rfdetr[onnx]'
```

!!! warning "Breaking: draw_synthetic_shape() now returns a tuple"

**`draw_synthetic_shape()` now returns `(image, polygon)` instead of `image`.**

Update every call site that unpacks only the image.

```python
# Before
img = draw_synthetic_shape(...)

# After
img, polygon = draw_synthetic_shape(...)
```

Deprecated in v1.6 → Removed in v1.8

!!! note "Deprecated: simplify and force arguments in RFDETR.export()"

**`RFDETR.export(..., simplify=..., force=...)`** — both arguments are no-ops.
Remove them from your calls.

```python
# Before (deprecated)
model.export("model.onnx", simplify=True, force=True)

# After
model.export("model.onnx")
```

Deprecated in v1.6 → Remove in v1.9

!!! note "Deprecated: rfdetr.util.* and rfdetr.deploy.* import paths"

Backward-compatibility shims are still active but emit `DeprecationWarning` on import.
Replace with the canonical paths listed in the table below.

| Deprecated module                 | Canonical replacement              |
| --------------------------------- | ---------------------------------- |
| `rfdetr.util.coco_classes`        | `rfdetr.assets.coco_classes`       |
| `rfdetr.util.misc`                | `rfdetr.utilities`                 |
| `rfdetr.util.logger`              | `rfdetr.utilities.logger`          |
| `rfdetr.util.box_ops`             | `rfdetr.utilities.box_ops`         |
| `rfdetr.util.files`               | `rfdetr.utilities.files`           |
| `rfdetr.util.package`             | `rfdetr.utilities.package`         |
| `rfdetr.util.get_param_dicts`     | `rfdetr.training.param_groups`     |
| `rfdetr.util.drop_scheduler`      | `rfdetr.training.drop_schedule`    |
| `rfdetr.util.visualize`           | `rfdetr.visualize.data`            |
| `rfdetr.deploy`                   | `rfdetr.export`                    |
| `rfdetr.models.segmentation_head` | `rfdetr.models.heads.segmentation` |

**Examples:**

```python
# Before (deprecated)
from rfdetr.util.coco_classes import COCO_CLASSES
from rfdetr.util.misc import get_rank, get_world_size, is_main_process, save_on_master
from rfdetr.util.logger import get_logger
from rfdetr.util.box_ops import box_cxcywh_to_xyxy, generalized_box_iou
from rfdetr.util.get_param_dicts import get_param_dict
from rfdetr.util.drop_scheduler import drop_scheduler
from rfdetr.util.visualize import save_gt_predictions_visualization
from rfdetr.deploy import export_onnx
from rfdetr.models.segmentation_head import SegmentationHead

# After
from rfdetr.assets.coco_classes import COCO_CLASSES
from rfdetr.utilities.distributed import get_rank, get_world_size, is_main_process, save_on_master
from rfdetr.utilities.logger import get_logger
from rfdetr.utilities.box_ops import box_cxcywh_to_xyxy, generalized_box_iou
from rfdetr.training.param_groups import get_param_dict
from rfdetr.training.drop_schedule import drop_scheduler
from rfdetr.visualize.data import save_gt_predictions_visualization
from rfdetr.export.main import export_onnx
from rfdetr.models.heads.segmentation import SegmentationHead
```

---

Upgrade 1.4 → 1.5

Breaking changes

!!! warning "Breaking: ModelConfig rejects unknown keyword arguments"

**`ModelConfig` now raises `ValidationError` on unknown keyword arguments.**

Previously, unrecognised fields were silently ignored. Remove or rename any
unrecognised keys you pass to `ModelConfig(...)`.

```python
# Before — silently accepted
config = ModelConfig(unknown_field=True)

# Now raises ValidationError — remove the unknown key
config = ModelConfig()
```

Deprecated in v1.5 → Removed in v1.7

!!! note "Deprecated: OPEN_SOURCE_MODELS replaced by ModelWeights enum"

**`OPEN_SOURCE_MODELS` constant** — use the `ModelWeights` enum instead. A
`DeprecationWarning` is emitted on access. See the
[API reference](../reference/rfdetr.md) for available enum values.

```python
# Before (deprecated)
from rfdetr import OPEN_SOURCE_MODELS

# After
from rfdetr.assets.model_weights import ModelWeights
```