SAMExporter: Converting SAM, MobileSAM, EfficientSAM and SAM 2/2.1 to ONNX

What SAMExporter solves, and for whom

Meta's Segment Anything models ship as PyTorch checkpoints. Running them means carrying torch and torchvision into whatever environment does the inference, which is awkward on edge devices, in C++ services, or anywhere the deployment target only speaks ONNX Runtime. SAMExporter exists to close that gap. It converts checkpoints into ONNX graphs and provides a runtime that drives them.

The audience is narrow but real: engineers who already have an ONNX Runtime deployment and want promptable segmentation inside it. The package covers SAM ViT-B, ViT-L and ViT-H, quantized variants of the same, MobileSAM, EfficientSAM-Ti and EfficientSAM-S, SAM2 Tiny through Large, SAM2.1 Tiny through Large, and SAM3 ViT-H. That is five upstream families behind one interface, which is the main reason to pick it over writing your own export script once.

It is not a training toolkit, not a segmentation model of its own, and not a hosted service. The README describes it as exporting and running existing models, nothing more.

The encoder/decoder split and why it shapes your deployment

Every SAM-family model has two halves with very different cost profiles. The image encoder is a ViT that runs once per image and produces an embedding. The decoder is small and runs per prompt, taking the embedding plus a point or a rectangle and returning masks. SAMExporter exports these as two separate ONNX files, and the inference module takes both paths as arguments.

The practical consequence is caching. Because the encoder output depends only on the image, you can run the encoder once and reuse the embedding across many prompts, which is the whole point of the split. The trade-off is that you now manage two artifacts per model instead of one, and both must come from the same checkpoint or the tensor shapes will not line up. There is no combined single-file export documented in the README.

Prompt types differ by family. SAM, MobileSAM and EfficientSAM accept points and rectangles. SAM3 ViT-H additionally accepts text prompts, which is what makes it open-vocabulary. If you need text-driven segmentation, the model choice is effectively made for you.

Installing SAMExporter and running a first segmentation

The package requires Python 3.11 or newer. The README installs torch and torchvision from the PyTorch CPU index first, then the package itself with a runtime extra. The runtime-cpu extra pulls onnxruntime; runtime-gpu, runtime-openvino, runtime-directml and runtime-qnn are the alternatives listed in pyproject.toml.

pip install torch==2.10.0 torchvision==0.25.0 --index-url https://download.pytorch.org/whl/cpu
pip install "samexporter[runtime-cpu]"

Windows users who intend to export models rather than only run them need the export extra, because onnxsim has no pre-built wheel for Windows and its source tarball exceeds the 260-character path limit. The README offers the export extra or enabling Windows Long Path support as the two fixes.

pip install "samexporter[runtime-cpu,export]"

Before exporting, download a checkpoint into original_models/. The README lists direct URLs for sam_vit_b_01ec64.pth, sam_vit_l_0b3195.pth, sam_vit_h_4b8939.pth and mobile_sam.pt. Exporting is two commands, one per half. This example uses ViT-H and also asks for a quantized encoder alongside the full-precision one.

python -m samexporter.export_encoder \
    --checkpoint original_models/sam_vit_h_4b8939.pth \
    --output output_models/sam_vit_h_4b8939.encoder.onnx \
    --model-type vit_h \
    --quantize-out output_models/sam_vit_h_4b8939.encoder.quant.onnx \
    --use-preprocess

The decoder export takes the same checkpoint and a model type. The README notes that removing --return-single-mask makes the decoder return multiple mask proposals instead of one, so the flag is a real behavioural switch, not a formality.

python -m samexporter.export_decoder \
    --checkpoint original_models/sam_vit_h_4b8939.pth \
    --output output_models/sam_vit_h_4b8939.decoder.onnx \
    --model-type vit_h \
    --return-single-mask

Inference then takes an image and a JSON prompt file, writes a PNG, and with --show displays the result. The README ships images/truck.jpg and images/truck_prompt.json as the worked example, and the repository has shell scripts such as infer_sam.sh and convert_all_meta_sam.sh for batch runs.

python -m samexporter.inference \
    --encoder_model output_models/sam_vit_h_4b8939.encoder.onnx \
    --decoder_model output_models/sam_vit_h_4b8939.decoder.onnx \
    --image images/truck.jpg \
    --prompt images/truck_prompt.json \
    --output output_images/truck.png \
    --show

EfficientSAM takes a different path: no export at all

EfficientSAM is the exception in this package. Its Ti and S variants use a distinct architecture, so the runtime expects --sam_variant efficient_sam rather than the default. More importantly, the README does not export these models; it downloads the official split ONNX pair from Hugging Face and runs it directly. The upstream project and its models are Apache-2.0 licensed, which is a different licence from the MIT licence on SAMExporter itself.

mkdir -p output_models/efficient_sam
curl -L https://huggingface.co/yunyangx/EfficientSAM/resolve/main/efficientsam_ti_encoder.onnx \
    -o output_models/efficient_sam/efficientsam_ti_encoder.onnx
curl -L https://huggingface.co/yunyangx/EfficientSAM/resolve/main/efficientsam_ti_decoder.onnx \
    -o output_models/efficient_sam/efficientsam_ti_decoder.onnx

The README states the Ti pair is about 40 MB combined, which is a useful sanity check on download size. Switching to EfficientSAM-S means changing the two model paths to the S encoder and decoder files; the rest of the invocation is unchanged. If your reason for using SAMExporter is CPU inference on modest hardware, this is the family to try first, because the export step is skipped entirely.

Where the export path is fragile

The source checkout pins the official model repositories as git submodules at specific revisions: SAM 1 at dca509fe793f601edb92606367a655c15ac00fdf, SAM 2 and 2.1 at 2b90b9f5ceec907a1c18123530e92e794ad901a4, and SAM 3 at 660a5e9e1b8b4c02c0ad97229b88a09a6e4ff5b7. The README is explicit that this exists so an upstream main branch cannot silently change an export. That is a sensible precaution, and it also tells you something about the failure mode: exporting depends on upstream code that moves independently of this package. Export commands prefer the pinned checkouts and keep installed-package fallbacks for the published wheel, so a pip install and a source checkout are not guaranteed to produce identical graphs.

Two other constraints are worth flagging. First, the dependency list pins exact versions: onnx==1.20.1, opencv-python==4.11.0.86, torch==2.10.0, torchvision==0.25.0, onnxscript==0.6.2, and segment-anything==1.0. If your environment already holds a different torch, installing SAMExporter will fight it. Second, the README documents Windows path-length trouble with onnxsim and offers no third option beyond the export extra or Long Path support.

The README does not document rollback, version-to-version graph compatibility, or what happens when a quantized encoder is paired with a full-precision decoder. Treat those as untested combinations rather than supported ones.

How this differs from leaving the models in PyTorch

The obvious alternative is running the original PyTorch checkpoints directly through Meta's segment-anything package, which is already a dependency here. That approach gives you the upstream reference implementation exactly as published, with no export step and no chance of an export bug changing your outputs. It also keeps you on PyTorch, which is fine on a GPU server and painful almost everywhere else.

The difference in approach is where the portability comes from. PyTorch gives you a Python runtime; ONNX gives you a graph that onnxruntime-gpu, onnxruntime-openvino, onnxruntime-directml and onnxruntime-qnn can each execute against different hardware backends. SAMExporter is the bridge to that second world, and the encoder/decoder split is what makes prompt reuse cheap. If your deployment is a Python process on a machine that already has torch installed, the export step buys you little and costs you a pinned dependency set.

Maintenance, licensing and what to verify before committing

The repository is not archived, and the last push was on 2026-08-30, the same day v0.5.0 was released. The project is MIT licensed, and pyproject.toml declares license-files covering LICENSE and third_party_licenses/*, which suggests upstream licence texts are carried alongside. That matters because the bundled model families are not all MIT: the README states EfficientSAM and its models are Apache-2.0. Check the third_party_licenses directory for the terms that apply to the specific checkpoint you ship, and treat the licence question as one for your own legal review rather than something this package settles for you.

Upgrade cost is dominated by the exact pins. A torch bump means waiting for a matching samexporter release, and a new upstream SAM revision means re-exporting every graph you depend on. Plan for re-export as a routine step, not a one-time migration.

The documentation site is listed at anylearning-oss.nrl.ai/docs/samexporter and prebuilt ONNX models at huggingface.co/nrl-ai/samexporter-onnx-models, so it is worth checking whether a model you need is already converted before running an export yourself.

Editorial conclusion

Adopt SAMExporter if you already run ONNX Runtime and want promptable segmentation without a PyTorch dependency at inference time. Skip it if you need a single self-contained graph, or if you cannot supply the original checkpoints. Verify first that your target runtime variant installs (runtime-cpu, runtime-gpu, runtime-openvino, runtime-directml or runtime-qnn) and that your decoder export matches the prompt type you intend to send.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. vietanhdev/samexporter on GitHub