Install samgeo v1.3.2: Remote Sensing SAM Setup Guide

End state: a Python environment named geo with segment-geospatial v1.3.2 installed, PyTorch running on your GPU, SAM3 weights cached locally, and a one-line sanity check that returns a mask for a GeoTIFF. That’s what this walkthrough gets you on Linux, macOS, or Windows.

The package – usually referenced as samgeo – wraps Meta’s Segment Anything Model so it understands georeferenced rasters. Published in JOSS (Wu & Osco, 2023) with a dedicated remote sensing benchmark by Osco et al. (2023), it’s the standard open-source bridge between SAM and geospatial workflows. The install, though? Genuinely fragile. Most failures come from PyTorch/CUDA mismatch or numpy resolver conflicts – not from samgeo itself.

System requirements for remote sensing SAM workflows

Check what you actually have before installing anything. SAM is heavy – running it on CPU is technically possible but painfully slow for any real raster. At least 8 GB of GPU memory is recommended to process large datasets without grinding to a halt (per the official README).

Pick your install path (and why pixi changed things)

Three working paths exist: pixi, conda, and pip. Until late 2025 the docs led with conda. That changed. Turns out, installing with uv or pip can be challenging on some platforms – especially Windows – because of complicated pytorch/cuda dependencies and numpy version conflicts. The official installation docs now recommend pixi for faster, more reliable dependency resolution than conda or mamba.

If you’ve tried installing samgeo before and got stuck in a 40-minute solver loop, pixi is what you want now. It’s a different mental model – project-scoped environments with a lockfile – but for this specific package on Windows, the difference is real.

Path A – pixi (recommended for Windows + SAM3)

# Linux / macOS
curl -fsSL https://pixi.sh/install.sh | sh

# Windows (PowerShell, no admin needed)
powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex"

# New project
pixi init geo
cd geo
# Edit pixi.toml with GPU/CPU config per the docs, then:
pixi install
pixi run jupyter lab

Close and reopen your terminal first so pixi is on PATH. The exact pixi.toml snippets per platform are in the official installation guide linked above.

Path B – conda-forge (the classic route)

conda create -n geo python=3.12
conda activate geo
conda install -c conda-forge segment-geospatial

# Force GPU PyTorch if conda picked the CPU build:
conda install -c conda-forge segment-geospatial "pytorch=*=cuda*"

Path C – pip with extras (CI / minimal envs)

Extras let you control dependencies granularly: [samgeo], [samgeo2], [samgeo3], [fast], [hq], [text] (Grounding DINO for SAM1/2 text prompts), [fer], [api] (FastAPI + Uvicorn for serving segmentation as a REST API), [all], and [extra].

pip install "segment-geospatial[samgeo3]"
# or for the full kitchen sink:
pip install "segment-geospatial[extra]"

The Windows SAM3 install trap

Windows SAM3 isn’t the same command sequence as Linux. One package in particular – you’d never guess it from the main docs – is required: triton-windows. Miss it and pip reports success, then SAM3 inference crashes with a Triton import error at runtime. The PyPI page has the full recipe:

conda create -n geo python=3.12
conda activate geo
conda install pytorch torchvision pytorch-cuda=12.1 -c pytorch -c nvidia
pip install "segment-geospatial[samgeo3]"
pip install triton-windows ipykernel jupyterlab

That last pip install line is buried in the PyPI README, not in the main installation guide. Silent failure is the worst kind.

First-time configuration: the SAM3 access wall

This is where most tutorials stop and most users get blocked. SAM3 weights are gated.

1. Create a free Hugging Face account.
2. Generate an access token, then run huggingface-cli login in the same conda env.
3. Visit huggingface.co/facebook/sam3 and submit the access request form.
4. Wait for approval.

Denied or still waiting? Download the SAM3 model from ModelScope instead – no access permission required. Place the files in ~/.cache/huggingface/hub/models--facebook--sam3 on Linux/macOS. The library checks that cache path regardless of where the weights came from. (This fallback is documented in the QGIS samgeo plugin README.)

For SAM1 and SAM2 there’s no gate – checkpoints download from Meta’s public CDN automatically the first time you instantiate the class.

Verify the install works

Three checks. Run them in order – each one rules out a different failure class.

# 1. Version check
python -c "import samgeo; print(samgeo.__version__)"
# Expect: 1.3.2 (as of March 2026)

# 2. GPU visibility
python -c "import torch; print(torch.cuda.is_available(), torch.version.cuda)"
# Expect: True 12.1 (or your CUDA version)

# 3. Smallest possible end-to-end run
python - <<'PY'
from samgeo import SamGeo, download_file
url = "https://huggingface.co/datasets/giswqs/geospatial/resolve/main/uc_berkeley.tif"
img = download_file(url)
sam = SamGeo(model_type="vit_h", automatic=True, sam_kwargs=None)
sam.set_image(img)
sam.generate("out.tif")
print("OK")
PY

If step 3 prints OK and writes out.tif, you’re done.

Common install errors (and the actual fix)

• Failed to load model: Torch not compiled with CUDA enabled – conda silently installed the CPU build of PyTorch. The official docs flag this exact error wording. Fix: conda install -c conda-forge segment-geospatial "pytorch=*=cuda*".
• OpenCV cv2.rectangle crash with non-contiguous arrays – you’re on an old samgeo with OpenCV 4.12. v1.3.2 specifically patches this. Upgrade.
• numpy version conflict during pip install – classic Windows pain. Switch to the pixi path.
• OSError: facebook/sam3 is gated – HF access isn’t approved yet, or you didn’t run huggingface-cli login. Use ModelScope as the fallback.
• Triton not available on Windows – you forgot pip install triton-windows.

What’s worth understanding about most of these errors: they happen at runtime, not at install time. pip exits 0, the environment looks clean, and the crash only appears when you try to load a model. That’s what makes samgeo installs feel unreliable – the feedback loop is long.

Upgrade and uninstall

pip install -U "segment-geospatial[samgeo3]"
# or
conda update -c conda-forge segment-geospatial

Migrating from v1.2.x is non-breaking. Same API for SamGeo, SamGeo2, SamGeo3 – v1.3.2 fixes the OpenCV interop regression and adds a show_points option; no config changes needed.

Clean uninstall:

conda deactivate
conda env remove -n geo
# Reclaim disk from model caches:
rm -rf ~/.cache/huggingface/hub/models--facebook--sam*
rm -rf ~/.cache/torch/hub/checkpoints/sam_vit_*

The cache removal matters. SAM model files are large – they don’t get deleted when you remove the conda environment, so they’ll quietly occupy disk until you clear them manually.

FAQ

Do I have to use SAM3, or is SAM1 still fine for remote sensing?

SAM1 is still fine. Not gated, runs on less VRAM, and has more community examples specifically for satellite imagery – fewer sharp edges in the install process too.

Why does the Windows install need pytorch-cuda=12.1 specifically, not the latest?

The pinned recipe exists because the prebuilt triton-windows wheels were compiled against CUDA 12.1. Mix in a different CUDA version and you’re back to the same class of torch/CUDA build mismatch the pixi path was invented to avoid – except now it’s a runtime crash, not a resolver error. Stick to 12.1 unless you’re ready to compile Triton from source.

Can I skip Python entirely and just use the QGIS plugin?

Yes – but the plugin still calls into a Python runtime; it doesn’t bundle one. You’ll need a samgeo-installed env for it to work. The plugin itself supports SAM1, SAM2, and SAM3 with text, point, and box prompts.

Next: open a Jupyter notebook in your geo env and load one of the official examples from samgeo.gishub.org/examples – start with sam3_interactive if your access is approved, or any SAM1 notebook if not.