SAM 2 (Segment Anything 2)

1.1.0 verified Mon Apr 27 auth: no python

SAM 2 is the second generation of the Segment Anything Model, supporting both image and video segmentation. Version 1.1.0 introduces new model variants (e.g., sam2.1_hiera_tiny) and improvements. Install from PyPI; requires Python >=3.10.

pip install sam2

Common errors

error ModuleNotFoundError: No module named 'sam2.predictor' ↓

cause The import path changed in sam2 1.1.0; 'predictor' module no longer exists.

fix

Use from sam2.sam2_image_predictor import SAM2ImagePredictor instead.

error RuntimeError: The checkpoint file does not match the model configuration. ↓

cause Mismatch between model config (e.g., sam2.1_hiera_t.yaml) and checkpoint (e.g., sam2.1_hiera_tiny.pt).

fix

Ensure you download the correct pair from the official GitHub releases.

error KeyError: 'image_encoder' ↓

cause Using an older checkpoint with new code or vice versa, or incorrect config path.

fix

Update both checkpoint and config to version 1.1.0. Use sam2.1_hiera_tiny.pt with sam2.1_hiera_t.yaml.

Warnings

breaking In version 1.1.0, the import for SAM2ImagePredictor changed from `sam2.predictor` to `sam2.sam2_image_predictor`. Old code using `from sam2.predictor import SAM2ImagePredictor` will break. ↓

fix Update import to `from sam2.sam2_image_predictor import SAM2ImagePredictor`.

gotcha The model checkpoint filename must match the config file. For example, `sam2.1_hiera_tiny.pt` pairs with `sam2.1_hiera_t.yaml`. Mismatch causes silent errors or wrong behavior. ↓

fix Always download the corresponding config and checkpoint from the GitHub releases.

deprecated The `build_sam2` function signature changed to accept config file path instead of model type string. Old code passing model type (e.g., 'sam2_hiera_l') is deprecated. ↓

fix Pass the config YAML path: build_sam2('path/to/config.yaml', checkpoint_path).

Imports

build_sam2

wrong

from sam2 import build_sam2

correct

from sam2.build_sam import build_sam2

build_sam2 is inside the build_sam module

SamPredictor

wrong

from sam2 import SamPredictor

correct

from sam2.predictor import SamPredictor

SamPredictor is in the predictor module

SAM2ImagePredictor

wrong

from sam2 import SAM2ImagePredictor

correct

from sam2.sam2_image_predictor import SAM2ImagePredictor

Full path changed in 1.1.0

Quickstart

Load a SAM 2 model, set an image, and predict a mask from a point prompt.

import torch
from sam2.build_sam import build_sam2
from sam2.sam2_image_predictor import SAM2ImagePredictor

checkpoint = "sam2.1_hiera_tiny.pt"
model_cfg = "sam2.1_hiera_t.yaml"

predictor = SAM2ImagePredictor(build_sam2(model_cfg, checkpoint))

import numpy as np
image = np.random.rand(1024, 1024, 3).astype(np.uint8)
predictor.set_image(image)

input_point = np.array([[500, 375]])
input_label = np.array([1])
mask, _, _ = predictor.predict(point_coords=input_point, point_labels=input_label)
print(mask.shape)