# How to Run SAM Locally: A Complete Guide to Segment Anything Model Inference

> Learn to run Segment Anything Model locally. Install the package, download a checkpoint, and use SamPredictor or SamAutomaticMaskGenerator for powerful image segmentation.

- Repository: [Meta Research/segment-anything](https://github.com/facebookresearch/segment-anything)
- Tags: how-to-guide
- Published: 2026-03-07

---

**To run SAM locally, install the `segment-anything` package, download a ViT-H, ViT-L, or ViT-B checkpoint, and use `SamPredictor` for interactive prompts or `SamAutomaticMaskGenerator` for fully automatic segmentation.**

The Segment Anything Model (SAM) from Meta's FAIR team enables promptable image segmentation through a foundation model architecture. Whether you need to extract objects via point clicks, bounding boxes, or generate masks for an entire image, learning how to run SAM locally gives you full control over inference without API dependencies. This guide covers installation, model setup, and both interactive and automatic workflows using the `facebookresearch/segment-anything` repository.

## Understanding SAM's Architecture

SAM consists of three tightly-coupled neural modules assembled in [`segment_anything/modeling/sam.py`](https://github.com/facebookresearch/segment-anything/blob/main/segment_anything/modeling/sam.py):

- **Image Encoder**: A Vision Transformer that extracts dense feature maps from input images. Implemented in [`segment_anything/modeling/image_encoder.py`](https://github.com/facebookresearch/segment-anything/blob/main/segment_anything/modeling/image_encoder.py), this module builds multi-scale patch embeddings and injects positional encodings.

- **Prompt Encoder**: Encodes user prompts (points, boxes, masks) into token embeddings aligned with image features. The logic resides in [`segment_anything/modeling/prompt_encoder.py`](https://github.com/facebookresearch/segment-anything/blob/main/segment_anything/modeling/prompt_encoder.py), handling point, box, and mask embeddings merged with a learnable prompt token.

- **Mask Decoder**: A lightweight transformer that fuses image and prompt embeddings to predict binary masks and confidence scores. Found in [`segment_anything/modeling/mask_decoder.py`](https://github.com/facebookresearch/segment-anything/blob/main/segment_anything/modeling/mask_decoder.py), it uses self-attention layers and a dynamic mask head to output masks at original resolution.

The factory function `sam_model_registry` in [`segment_anything/__init__.py`](https://github.com/facebookresearch/segment-anything/blob/main/segment_anything/__init__.py) creates a SAM instance given a model type (`vit_h`, `vit_l`, `vit_b`) and checkpoint path.

## Prerequisites and Installation

### System Requirements

SAM requires **Python ≥ 3.8** and **PyTorch ≥ 1.7**. GPU acceleration is recommended for the image encoder, though CPU inference is possible with reduced performance.

### Installing the Package

Install directly from the GitHub repository:

```bash
pip install git+https://github.com/facebookresearch/segment-anything.git

```

For editable installs or development work, clone the repository and install in development mode.

## Downloading Model Checkpoints

SAM provides three model sizes. Download the default ViT-H checkpoint:

```bash
wget https://dl.fbaipublicfiles.com/segment_anything/sam_vit_h_4b8939.pth -O sam_vit_h.pth

```

Available model types:
- `vit_h`: ViT-H (default, most accurate, 2.4GB)
- `vit_l`: ViT-L (medium, 1.2GB)
- `vit_b`: ViT-B (smallest, fastest, 375MB)

## Running SAM Locally with Python

### Interactive Segmentation Using SamPredictor

For point-and-click or bounding box workflows, use `SamPredictor` from [`segment_anything/predictor.py`](https://github.com/facebookresearch/segment-anything/blob/main/segment_anything/predictor.py). This wrapper handles image preprocessing and prompt encoding.

```python
from segment_anything import SamPredictor, sam_model_registry

# Load model

sam = sam_model_registry["vit_h"](checkpoint="sam_vit_h.pth")
predictor = SamPredictor(sam)

# Load image (accepts NumPy arrays, PIL images, or file paths)

predictor.set_image("path/to/image.jpg")

# Define prompts: point coordinates and labels (1=foreground, 0=background)

point_coords = [[425, 350]]
point_labels = [1]

# Optional: add bounding box [x1, y1, x2, y2]

box = [200, 150, 600, 500]

# Generate masks

masks, scores, logits = predictor.predict(
    point_coords=point_coords,
    point_labels=point_labels,
    box=box,
    multimask_output=True,  # Returns 3 masks for ambiguous prompts

)

# masks: (N, H, W) boolean array

# scores: confidence scores for each mask

```

### Automatic Mask Generation

For prompt-free segmentation that generates masks for all objects in an image, use `SamAutomaticMaskGenerator` from [`segment_anything/automatic_mask_generator.py`](https://github.com/facebookresearch/segment-anything/blob/main/segment_anything/automatic_mask_generator.py).

```python
from segment_anything import SamAutomaticMaskGenerator, sam_model_registry

# Initialize model

sam = sam_model_registry["vit_h"](checkpoint="sam_vit_h.pth")
mask_generator = SamAutomaticMaskGenerator(sam)

# Generate masks for entire image

image_path = "path/to/image.jpg"
masks = mask_generator.generate(image_path)

# Returns list of dictionaries containing:

# - segmentation: binary mask

# - bbox: bounding box [x, y, w, h]

# - area: mask area in pixels

# - predicted_iou: model confidence

```

## Command-Line Interface for Batch Processing

The repository includes [`scripts/amg.py`](https://github.com/facebookresearch/segment-anything/blob/main/scripts/amg.py) for processing images without writing Python code:

```bash
python scripts/amg.py \
    --checkpoint sam_vit_h.pth \
    --model-type vit_h \
    --input path/to/image_or_folder \
    --output ./masks_output \
    --device cuda

```

This script wraps `SamAutomaticMaskGenerator` and supports batch processing of entire directories.

## Optimizing for Production: ONNX Export

For deployment environments without PyTorch dependencies, export the mask decoder to ONNX using [`scripts/export_onnx_model.py`](https://github.com/facebookresearch/segment-anything/blob/main/scripts/export_onnx_model.py):

```bash
python scripts/export_onnx_model.py \
    --checkpoint sam_vit_h.pth \
    --model-type vit_h \
    --output sam_onnx.onnx

```

This enables inference in production systems using ONNX Runtime while maintaining the model's promptable segmentation capabilities. Note that the image encoder still requires computation, so you may need to optimize or cache encoded image features separately.

## Interactive Examples and Notebooks

The `notebooks/` directory contains fully functional Jupyter notebooks:

- `notebooks/predictor_example.ipynb`: Demonstrates point and box prompts using `SamPredictor`
- `notebooks/automatic_mask_generator_example.ipynb`: Shows full-image mask generation workflows

These notebooks provide interactive environments for experimenting with segmentation parameters before integrating into production pipelines.

## Summary

- **SAM** consists of three core modules: an image encoder ([`image_encoder.py`](https://github.com/facebookresearch/segment-anything/blob/main/image_encoder.py)), prompt encoder ([`prompt_encoder.py`](https://github.com/facebookresearch/segment-anything/blob/main/prompt_encoder.py)), and mask decoder ([`mask_decoder.py`](https://github.com/facebookresearch/segment-anything/blob/main/mask_decoder.py)), assembled in [`sam.py`](https://github.com/facebookresearch/segment-anything/blob/main/sam.py).
- Install the package with `pip install git+https://github.com/facebookresearch/segment-anything.git` and download checkpoints from the official Meta URLs.
- Use `SamPredictor` (from [`predictor.py`](https://github.com/facebookresearch/segment-anything/blob/main/predictor.py)) for interactive workflows with point and box prompts.
- Use `SamAutomaticMaskGenerator` (from [`automatic_mask_generator.py`](https://github.com/facebookresearch/segment-anything/blob/main/automatic_mask_generator.py)) for prompt-free full-image segmentation.
- Process batches via the command-line script [`scripts/amg.py`](https://github.com/facebookresearch/segment-anything/blob/main/scripts/amg.py) or explore interactive examples in the `notebooks/` directory.

## Frequently Asked Questions

### What hardware do I need to run SAM locally?

SAM requires a machine with Python 3.8+ and PyTorch 1.7+. While the model can run on CPU, a CUDA-enabled GPU with at least 8GB VRAM is recommended for the ViT-H checkpoint. The smaller ViT-B model (375MB) runs efficiently on CPU and requires less memory, making it suitable for laptops or edge devices.

### Can I run SAM without installing PyTorch in my production environment?

Yes. You can export the mask decoder to ONNX format using [`scripts/export_onnx_model.py`](https://github.com/facebookresearch/segment-anything/blob/main/scripts/export_onnx_model.py), then deploy using ONNX Runtime. This removes the PyTorch dependency while preserving the model's promptable segmentation capabilities. Note that the image encoder still requires computation, so you may need to optimize or cache encoded image features separately.

### What is the difference between SamPredictor and SamAutomaticMaskGenerator?

`SamPredictor` (defined in [`segment_anything/predictor.py`](https://github.com/facebookresearch/segment-anything/blob/main/segment_anything/predictor.py)) is designed for interactive use where you provide specific prompts like point coordinates or bounding boxes to segment particular objects. `SamAutomaticMaskGenerator` (from [`segment_anything/automatic_mask_generator.py`](https://github.com/facebookresearch/segment-anything/blob/main/segment_anything/automatic_mask_generator.py)) requires no prompts and instead generates masks for all objects in an image automatically, returning a list of masks with bounding boxes and confidence scores.

### How do I process multiple images in batch mode?

Use the command-line script [`scripts/amg.py`](https://github.com/facebookresearch/segment-anything/blob/main/scripts/amg.py) to process directories without writing Python code. Run `python scripts/amg.py --checkpoint sam_vit_h.pth --model-type vit_h --input /path/to/images --output /path/to/masks` to automatically generate masks for all images in a folder. For custom logic, wrap `SamAutomaticMaskGenerator` in a Python loop that iterates over your image directory.