How to Export an RF-DETR Model to CoreML Format: A Complete Guide

To export an RF-DETR model to CoreML, use the unified model.export(format="coreml") API or the CLI command rfdetr export --format coreml, which routes through src/rfdetr/export/_backend.py to the CoreML converter in src/rfdetr/export/_coreml/converter.py to generate a .mlpackage file for Apple devices.

RF-DETR is an open-source transformer-based object detection model developed by Roboflow. When deploying to iOS or macOS, converting to CoreML format is essential for optimized on-device inference. The RF-DETR repository provides a unified export system that handles this conversion through a modular backend architecture that dispatches format-specific logic to dedicated converter modules.

Prerequisites and Installation

Before exporting, you must install the CoreML tools dependency. The RF-DETR source code in src/rfdetr/export/_coreml/__init__.py checks for coremltools availability at runtime and raises an informative ImportError if the package is missing (as verified in the test suite).

pip install coremltools

Understanding the Export Architecture

The export system uses a three-tier architecture to handle format conversion:

• Backend Router (src/rfdetr/export/_backend.py): Dispatches export requests to format-specific handlers based on the format argument. When format="coreml" is specified, it invokes _export_coreml_format.
• CoreML Converter (src/rfdetr/export/_coreml/converter.py): Contains the export_coreml function that executes the Torch-to-CoreML conversion pipeline, including graph capture and operator mapping.
• Public Interface (src/rfdetr/export/main.py): Exposes the export() method on RF-DETR model classes and the CLI entry point, forwarding requests to the backend router.

Export Methods

You can export your trained RF-DETR model using either the Python API or the command-line interface.

Python API Method

Instantiate your model and call the export method with a dummy input tensor matching your expected image dimensions.

from rfdetr import RFDETRSmall
import torch

# Load pretrained model

model = RFDETRSmall(pretrained=True)

# Prepare dummy input with shape (batch, channels, height, width)

example_input = {"pixel_values": torch.randn(1, 3, 640, 640)}

# Export to CoreML

output_path = model.export(
    format="coreml",
    inputs=example_input,
    output_dir="exported_models",
    variant_name="small",
    verbose=True
)

print(f"CoreML package saved to: {output_path}")

The function returns the path to the generated .mlpackage file, saved as <output_dir>/<variant_name>.mlpackage according to the implementation in src/rfdetr/export/_coreml/converter.py.

Command Line Interface

For automated pipelines or shell scripts, use the rfdetr export CLI defined in src/rfdetr/export/main.py:

rfdetr export \
    --model rfdetr-small \
    --format coreml \
    --output-dir exported_models \
    --variant-name small

This invokes the same export_coreml logic without requiring Python script writing, routing through the backend selector to generate the CoreML package.

Technical Deep Dive: The Conversion Pipeline

The export_coreml function in src/rfdetr/export/_coreml/converter.py executes a five-step conversion process:

1. Availability Check: Validates that coremltools is importable via src/rfdetr/export/_coreml/__init__.py.
2. Torch Graph Export: Uses torch.export to capture the model's FX graph representation.
3. Operator Decomposition: Runs PyTorch decomposition passes to replace unsupported operations with CoreML-compatible equivalents.
4. Registry Patching: The file src/rfdetr/export/_coreml/torch_ops.py patches the CoreML Torch-op registry to add missing operators like __and__ and bitwise_and, ensuring complete graph coverage for transformer attention mechanisms.
5. Model Packaging: Calls coremltools.converters.convert to generate the .mlpackage containing the model weights, input/output specifications, and metadata (including notes fields).

Summary

• RF-DETR supports CoreML export through a unified interface exposed in src/rfdetr/export/main.py.
• The export pipeline routes through src/rfdetr/export/_backend.py and executes conversion logic in src/rfdetr/export/_coreml/converter.py.
• Two methods are available: Python API (model.export(format="coreml")) and CLI (rfdetr export --format coreml).
• The converter patches CoreML's operator registry via src/rfdetr/export/_coreml/torch_ops.py to handle custom transformer operations.
• The output is a .mlpackage file saved to <output_dir>/<variant_name>.mlpackage, ready for deployment on iOS 15+ and macOS.

Frequently Asked Questions

What iOS version is required for RF-DETR CoreML models?

CoreML models exported from RF-DETR typically require iOS 15 or later, depending on the specific transformer operators used. The coremltools converter automatically targets the minimum deployment version based on the model architecture. Always validate inference on your target iOS version, as attention mechanisms may require newer CoreML features available in recent iOS releases.

Can I export quantized RF-DETR models to CoreML?

The current implementation in src/rfdetr/export/_coreml/converter.py handles standard floating-point conversion. For quantized models, apply PyTorch quantization to your model instance before calling export(), then verify compatibility using coremltools quantization utilities. The export pipeline preserves compute unit specifications as defined in the conversion parameters.

How do I handle custom input sizes when exporting to CoreML?

Modify the example_input tensor dimensions in the Python API to match your deployment requirements. The dummy input tensor shape (batch, 3, height, width) directly determines the CoreML model's input specification. Ensure your input size matches the training resolution (commonly 640×640 for RF-DETR) to maintain detection accuracy, or retrain with your target resolution before export.

Where is the exported .mlpackage file saved?

By default, the file is saved to <output_dir>/<variant_name>.mlpackage as implemented in src/rfdetr/export/_coreml/converter.py. If you omit variant_name, the system derives a name from the model checkpoint. The export() function returns the absolute path string to the generated package, allowing programmatic access to the output location.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}