How to Install SAM 3.1 (Segment Anything): 2026 Deploy Guide

The number one mistake people make installing Segment Anything? They google the name, land on the original 2023 facebookresearch/segment-anything repo, follow the README, then wonder why nothing they read on Reddit or in Meta’s recent blog posts applies. Three separate repos exist now – SAM 1, SAM 2, and SAM 3 – and the checkpoints are not cross-compatible. It’s less like upgrading software and more like swapping firmware between different hardware generations: same brand, completely different instruction sets.

If you want what people mean today when they say SAM, you want SAM 3.1, released March 27, 2026. This guide walks through the install path that actually works in 2026 – not the one Google’s top results still describe.

Why SAM 3.1 and not SAM 2

SAM 3 introduces open-vocabulary concept segmentation plus a presence token that improves discrimination between closely related text prompts – “a player in white” vs. “a player in red,” for example (per the sam3 README). That’s the practical difference: you can prompt with text now, not just clicks and boxes.

848M parameters, DETR-based detector, tracker that inherits SAM 2’s transformer architecture. The SAM 3.1 release added a roughly 7x speedup at 128 objects on a single H100 GPU compared to SAM 3’s November 2025 release (documented in RELEASE_SAM3p1.md) – that’s the Object Multiplex tracker at work. Single-object use? The speedup matters less. The install path is the same either way.

The catch: checkpoints are gated on Hugging Face and require an access request plus hf auth login before you can download anything. SAM 2 weights were ungated – that’s why most tutorials haven’t caught up to this step yet. Plan for a delay before the actual download becomes possible.

System requirements

Two notes from the field. An RTX 3060 (12 GB VRAM) hits 25-30 FPS on 1080p video with SAM 2, and CPU-only runs about 15-20x slower than GPU – per community testing as of 2024; check recent benchmarks for SAM 3 numbers. And on Windows: the official INSTALL.md strongly recommends WSL with Ubuntu – native Windows builds will fight you on the CUDA extension.

Install SAM 3.1 – the path that works

Create a clean conda env first. Sharing an env with a previous SAM install is the second most common failure mode, right after picking the wrong repo.

# 1. Fresh environment
conda create -n sam3 python=3.12 -y
conda activate sam3

# 2. PyTorch with CUDA 12.8 wheels (match your driver)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

# 3. Clone and install SAM 3
git clone https://github.com/facebookresearch/sam3.git
cd sam3
pip install -e ".[notebooks]"

# 4. Optional but recommended: flash-attn-3 for fast inference
# Order matters - install einops + ninja FIRST, then flash-attn-3 with --no-deps
pip install einops ninja
pip install flash-attn-3 --no-deps --index-url https://download.pytorch.org/whl/cu128
pip install git+https://github.com/ronghanghu/cc_torch.git

The flash-attn-3 step is where deploys fail silently. The official command uses --no-deps and points at the CUDA 12.8 PyTorch wheel index (per the sam3 README). Let pip resolve dependencies normally and it will try to pull a torch version that conflicts with step 2. Skip the flag, spend an hour debugging.

Get the checkpoints (the gated part)

1. Go to huggingface.co/facebook/sam3 and click “Request access.” Approval is usually fast but not instant.
2. Generate a Hugging Face token (Settings → Access Tokens, read scope is enough).
3. Authenticate locally: pip install huggingface_hub && hf auth login – paste your token when prompted.
4. Download: huggingface-cli download facebook/sam3 --local-dir ./checkpoints

Worth doing: After downloading, run sha256sum on the checkpoint file and compare against the hash in the repo README. Corrupted partial downloads will load and produce gibberish masks rather than throwing a clean error.

How long does access approval actually take? That’s an open question – Meta hasn’t published SLAs for gated model access, and reports in the community range from minutes to a few days depending on account history. Request early. Don’t assume you can run the install end-to-end in one sitting.

First inference – verify it works

The minimum viable test. If this runs without errors, the install is healthy. Note: check the current sam3 README for exact class names – the API is new and names may shift between minor releases.

import torch
from PIL import Image
from sam3.model_builder import build_sam3_image_model
from sam3.model.sam3_image_processor import Sam3Processor

model = build_sam3_image_model()
processor = Sam3Processor(model)

image = Image.open("test.jpg")
state = processor.set_image(image)
out = processor.set_text_prompt(state=state, prompt="a red bicycle")

masks, boxes, scores = out["masks"], out["boxes"], out["scores"]
print(f"Detected {len(masks)} instances, top score: {scores.max().item():.3f}")

Non-empty masks tensor plus a score above ~0.3 means the install is working end to end. Score of 0.0 with empty masks? The prompt found nothing – try “person” on a photo with people before assuming the install is broken.

For video and the SAM 3.1 speedup: use build_sam3_multiplex_video_predictor(), not the default build_sam3_video_predictor(). The multiplex path is what delivers the ~7x speedup for high object counts (up to 128 objects). Default predictor still works – it just won’t be as fast at scale. The example notebook is sam3.1_video_predictor_example.ipynb in the repo.

The four errors you’ll actually hit

1. “Failed to build the SAM 2 CUDA extension” – but install reports success. Turns out this is by design: the build errors are hidden unless you pass -v to pip (per INSTALL.md). The cost is real but limited – small hole and sprinkle cleanup in output masks is skipped, but most results still look fine. To make the failure loud enough to debug, set SAM2_BUILD_ALLOW_ERRORS=0 before running pip install.

2. “CUDA error: no kernel image is available for execution on the device.” The CUDA kernel wasn’t compiled for your GPU’s compute capability. Fix: set TORCH_CUDA_ARCH_LIST to your GPU’s capability (“8.0” for A100, “9.0” for H100) before reinstalling. That forces compilation for the right target.

3. “RuntimeError: No available kernel.” CUDA/PyTorch version mismatch. Uninstall existing PyTorch, run nvcc --version, reinstall PyTorch matching that CUDA version, make sure CUDA_HOME points to your toolkit directory.

4. “Permission denied” downloading the checkpoint. Access request not approved yet, or your token lacks read permission on gated repos. Re-issue with read access, re-run hf auth login.

Upgrading from SAM 2

Don’t just pip install SAM 3 on top of an existing SAM 2 env. The sam2 README is explicit: uninstall first via pip uninstall SAM-2 (note the dash – SAM-2, not sam2), pull the latest code, then reinstall. The package name catches people.

Full clean uninstall:

pip uninstall SAM-2 sam3 -y
rm -rf ~/.cache/torch/hub/checkpoints/sam*
conda deactivate
conda env remove -n sam3

The cache cleanup matters. Leftover SAM 2 checkpoints in the torch hub cache can shadow new SAM 3 weights if config paths aren’t absolute.

FAQ

Can I use the original SAM 1 code with SAM 3 checkpoints?

No. Different architectures – SAM 3 has a DETR-based detector and a presence token the SAM 1 codebase can’t load. Matching repo to checkpoint is non-negotiable.

Do I need flash-attn-3 to make SAM 3 work?

No – it’s an optional speedup. Skip it if the install fights you. SAM 3 falls back to PyTorch’s built-in scaled dot-product attention and produces identical masks, just slower. The gap is most noticeable on long video sequences where memory attention dominates; for single-image work on a reasonably modern GPU, you probably won’t notice. If you’re debugging an install at 11pm, skip flash-attn-3 first and add it later when everything else is confirmed working.

What if I can’t get Hugging Face access approved?

Fall back to SAM 2.1 – checkpoints are Apache 2.0 licensed and ungated. For one-off jobs, the hosted Meta demo at ai.meta.com/sam2 exists, but you lose programmatic access. Request SAM 3 access early; it’s the bottleneck, not the install itself.

Once your verification script prints a non-empty mask count, the next useful move is pointing the predictor at a 30-second test video and timing the inference. That gives you a real baseline for your hardware – and tells you whether the Object Multiplex path is worth pursuing or whether single-object tracking is all you need. The SAM 3 paper (arXiv:2511.16719) has the architecture details if you want to understand what’s actually happening under the hood.