Skip to content

Installation

Supported environments

The initial samstars release supports Python 3.10 through 3.12 on these 64-bit platforms:

Platform Baseline Optional acceleration
Ubuntu 20.04 or newer on x86-64 CPU NVIDIA CUDA
macOS 14 or newer on Apple Silicon CPU PyTorch MPS and TensorFlow Metal

CPU execution is the supported baseline and is used by the examples unless stated otherwise. Windows, Linux ARM64, and Intel macOS are not currently tested release targets.

Install the library from PyPI

1
2
python -m pip install --upgrade pip
python -m pip install samstars

This installs the geospatial libraries and CPU-capable machine-learning stack needed by the documented workflows. Accelerator-specific setup is separate so that a normal installation does not require CUDA or Metal.

On Linux, use PyTorch's CPU-only package index when you do not want pip to install NVIDIA runtime libraries:

1
2
3
python -m pip install "torch>=2.3,<3" "torchvision>=0.18,<1" \
  --index-url https://download.pytorch.org/whl/cpu
python -m pip install samstars

samstars does not bundle trained model files. See Training and Segmentation.

Verify:

1
2
python -c "import samstars, torch, tensorflow as tf; print('samstars import ok'); print('torch', torch.__version__); print('tensorflow', tf.__version__)"
pip show samstars

NVIDIA CUDA on Linux

CUDA builds of PyTorch and Torchvision must be installed as a matched pair. Use the official PyTorch installation selector to install a pair within the supported ranges (torch>=2.3,<3 and torchvision>=0.18,<1), then install samstars:

1
2
3
# Run the command produced by the PyTorch selector first.
python -m pip install "tensorflow[and-cuda]>=2.15,<2.19"
python -m pip install samstars

The TensorFlow command follows the official TensorFlow pip guide and requires a compatible NVIDIA driver. If TensorFlow GPU support is not needed, omit that command and let samstars install standard TensorFlow. PyTorch and TensorFlow detect accelerators independently: device="cuda" controls the SAM stage, while TensorFlow controls StarDist. Set stardist_cpu=True when only the SAM stage should use CUDA.

Check CUDA availability:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
python - <<'PY'
import torch
import tensorflow as tf

print("torch:", torch.__version__)
print("cuda runtime:", torch.version.cuda)
print("cuda available:", torch.cuda.is_available())
print("device:", torch.cuda.get_device_name(0) if torch.cuda.is_available() else "none")
print("tensorflow:", tf.__version__)
print("tensorflow GPUs:", tf.config.list_physical_devices("GPU"))
PY

Use device="cuda" only when torch.cuda.is_available() returns True.

Apple Silicon acceleration

The standard Apple Silicon PyTorch build can use MPS when it is available. TensorFlow Metal support is optional; see Apple's TensorFlow acceleration guide for host requirements:

1
python -m pip install "samstars[metal]"

The metal extra installs tensorflow-metal>=1.2,<2. Because the plug-in does not declare a TensorFlow compatibility range in its package metadata, verify both frameworks after installation:

1
2
3
4
5
6
7
8
9
python - <<'PY'
import torch
import tensorflow as tf

print("mps built:", torch.backends.mps.is_built())
print("mps available:", torch.backends.mps.is_available())
print("tensorflow:", tf.__version__)
print("tensorflow GPUs:", tf.config.list_physical_devices("GPU"))
PY

Use device="mps" only when torch.backends.mps.is_available() returns True. Otherwise, keep device="cpu". TensorFlow Metal availability does not change the PyTorch device setting.

Conda development environments

The repository environment files provide platform-specific Python 3.10 CPU development baselines. From the repository root, use the file for your platform and then install the checkout in editable mode:

1
2
3
4
# Ubuntu x86-64
conda env create -f environment.ubuntu.samstars.yml
conda activate samstars
python -m pip install -e .

1
2
3
4
# Apple Silicon macOS
conda env create -f environment.macos.samstars.yml
conda activate samstars
python -m pip install -e .

For Apple Silicon development with TensorFlow Metal, replace the final command with python -m pip install -e ".[metal]". The Ubuntu environment pins CPU builds of PyTorch and Torchvision. For CUDA development, uninstall those two packages after creating the environment, run the matched installation command from the PyTorch selector, and then install the checkout:

1
2
3
python -m pip uninstall -y torch torchvision
# Run the matched CUDA command produced by the PyTorch selector.
python -m pip install -e .

Verify that torch.version.cuda is non-empty and torch.cuda.is_available() is True before selecting device="cuda".