Skip to main content

​
Installation

This guide will walk you through installing SAM 3 and its dependencies on your system.

​
Prerequisites

Before installing SAM 3, ensure your system meets the following requirements:
  • Python: 3.12 or higher (3.8+ supported, 3.12 recommended)
  • PyTorch: 2.7 or higher
  • CUDA: CUDA-compatible GPU with CUDA 12.6 or higher
  • Operating System: Linux (recommended), macOS, or Windows with WSL
For optimal performance, we recommend using a GPU with at least 16GB of VRAM. SAM 3 has 848M parameters and benefits from GPU acceleration.

​
Installation Steps

1

Create a Conda Environment

Create and activate a new Conda environment with Python 3.12:
conda create -n sam3 python=3.12
conda deactivate
conda activate sam3
If you don’t have Conda installed, you can download it from Anaconda or Miniconda.
2

Install PyTorch with CUDA Support

Install PyTorch 2.7 with CUDA 12.6 support:
pip install torch==2.7.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
Make sure to install the CUDA-enabled version of PyTorch. The CPU-only version will be significantly slower for inference.
Verify your PyTorch installation:
import torch
print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")
3

Clone the Repository

Clone the SAM 3 repository from GitHub:
git clone https://github.com/facebookresearch/sam3.git
cd sam3
4

Install SAM 3

Install SAM 3 in editable mode:
pip install -e .
This will install SAM 3 along with its core dependencies:
  • timm>=1.0.17 - PyTorch Image Models
  • numpy>=1.26,<2 - Numerical computing
  • tqdm - Progress bars
  • ftfy==6.1.1 - Text encoding fixes
  • regex - Regular expressions
  • iopath>=0.1.10 - File I/O utilities
  • typing_extensions - Type hints
  • huggingface_hub - Model downloads
5

Install Optional Dependencies

Depending on your use case, install additional dependencies:
# For running example notebooks
pip install -e ".[notebooks]"
Notebooks dependencies include:
  • matplotlib, jupyter, notebook - Jupyter environment
  • ipywidgets, ipycanvas, ipympl - Interactive widgets
  • pycocotools - COCO dataset tools
  • decord, opencv-python - Video processing
  • einops, scikit-image, scikit-learn - Image processing
Development dependencies include:
  • pytest, pytest-cov - Testing
  • black, ufmt, usort - Code formatting
  • yt-dlp, pandas - Data processing
Training dependencies include:
  • hydra-core, submitit - Job management
  • tensorboard - Training visualization
  • scipy, torchmetrics - Metrics and optimization

​
Checkpoint Access

Before using SAM 3, you need to request access to the model checkpoints.
1

Request Checkpoint Access

Request access to the SAM 3 checkpoints on Hugging Face:
  1. Visit the SAM 3 Hugging Face repository
  2. Click “Request Access” and follow the prompts
  3. Wait for approval (usually granted within a few hours)
2

Authenticate with Hugging Face

Once approved, authenticate your local environment:
pip install huggingface_hub
huggingface-cli login
When prompted, enter your Hugging Face access token. You can generate a token at huggingface.co/settings/tokens.
The authentication token is stored locally and used automatically when downloading checkpoints.

​
Verify Installation

Verify that SAM 3 is installed correctly: 
import sam3
import torch

print(f"SAM 3 version: {sam3.__version__}")
print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")

# Test model import
from sam3 import build_sam3_image_model
print("SAM 3 installation successful!")

​
Troubleshooting

If you encounter CUDA out of memory errors:
  • Reduce batch size or image resolution
  • Use mixed precision training with torch.autocast
  • Ensure no other processes are using GPU memory
  • Consider using a GPU with more VRAM
If you get import errors:
  • Ensure you’re using the correct Conda environment: conda activate sam3
  • Verify all dependencies are installed: pip list | grep sam3
  • Try reinstalling: pip uninstall sam3 && pip install -e .
If checkpoint downloads fail:
  • Verify you have access to the Hugging Face repository
  • Check your authentication: huggingface-cli whoami
  • Ensure you have a stable internet connection
  • Try downloading manually from the Hugging Face hub
If PyTorch doesn’t detect CUDA:
  • Verify CUDA is installed: nvidia-smi
  • Ensure PyTorch CUDA version matches your system CUDA
  • Reinstall PyTorch with the correct CUDA version
  • Check the PyTorch installation guide

​
Next Steps

Now that SAM 3 is installed, you’re ready to run your first segmentation!

Quick Start Guide

Learn how to perform your first image and video segmentation with SAM 3

Build docs developers (and LLMs) love

Get started for freeTalk to us