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 | |
For optional GPU support, see NVIDIA CUDA on Linux or Apple Silicon acceleration.
On Linux, use PyTorch's CPU-only package index when you do not want pip to install NVIDIA runtime libraries:
1 2 3 | |
Verify:
1 2 | |
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 | |
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 proposal generation, while TensorFlow controls refinement. Set
stardist_cpu=True when only proposal generation should use CUDA.
Check CUDA availability:
1 2 3 4 5 6 7 8 9 10 11 | |
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 | |
Check both frameworks after installation:
1 2 3 4 5 6 7 8 9 | |
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 | |
1 2 3 4 | |
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 | |
Verify that torch.version.cuda is non-empty and
torch.cuda.is_available() is True before selecting device="cuda".