SAM3‑Tools is a lightweight Python application offering both a simple GUI and command‑line interface for running Meta AI’s Segment Anything 3 (SAM3) model. It supports box selection, auto segmentation, point‑based segmentation and text prompt segmentation.
- CLI interface for integration with Darktable
- Basic GUI interface
- Works with Darktable via PFM output
- Works with the Darktable SAM3 plugin – GitHub repo
- Segmentation modes: Prompt, Box, Auto, Points
- Cross‑platform: Linux, macOS, Windows
The installation script is the easiest way to install sam3-tools. It will:
- Install dependencies
- Clone the repository
- Create a virtual environment
- Install the Python app and its requirements
- Download the SAM3 model checkpoints (Optional)
- Install the Darktable plugin (Optional)
Installation script Video for Linux, Windows and macOS → https://youtu.be/i08ccYK93Sg
bash <(curl -fsSL https://raw.githubusercontent.com/AyedaOk/sam3-tools/main/installer/linux_install.sh)
powershell -ExecutionPolicy Bypass -Command "iwr https://raw.githubusercontent.com/AyedaOk/sam3-tools/main/installer/win_install.ps1 | iex"
bash <(curl -fsSL "https://raw.githubusercontent.com/AyedaOk/sam3-tools/main/installer/mac_install.sh")
Install the following first:
-
Arch:
sudo pacman -S curl git -
Debian/Ubuntu:
sudo apt install curl git -
Fedora:
sudo dnf install -y curl git
Install UV:
curl -LsSf https://astral.sh/uv/install.sh | sh
To add $HOME/.local/bin to your PATH, either restart your shell or run:
source $HOME/.local/bin/env
Or this for fish:
source $HOME/.local/bin/env.fish
Create the installation directory:
mkdir -p $HOME/.local/opt/
Clone the repo, create the virtual environment and install the Python App:
cd $HOME/.local/opt/
git clone https://github.com/AyedaOk/sam3-tools.git
cd sam3-tools
uv venv
Install application:
If your GPU is running CUDA 13, run this command first. You can check your version by running nvidia-smi:
uv pip install --pre --index-url https://download.pytorch.org/whl/nightly/cu130 torch torchvision
uv pip install -r requirements.txt
If you don't have a GPU and want to install it for CPU only:
uv pip install --pre --index-url https://download.pytorch.org/whl/cpu torch torchvision
uv pip install -r requirements.txt
Otherwise, run this command:
uv pip install -r requirements.txt
SAM3 checkpoints are gated on Hugging Face, so you must request access and log in before first run.
Request access here (wait for approval): https://huggingface.co/facebook/sam3
Create a Hugging Face access token (token type should be Read): https://huggingface.co/settings/tokens
Log in from your terminal using the access token:
uv run hf auth login
Download the model files into the HF cache (~/.cache/huggingface/).
uv run python -c "from transformers import Sam3Model, Sam3Processor; Sam3Model.from_pretrained('facebook/sam3'); Sam3Processor.from_pretrained('facebook/sam3'); print('SAM3 downloaded into ~/.cache/huggingface/')"
To install like a system-wide “app”:
Install the launcher
sudo cp ./launcher/sam3-tools /usr/local/bin/sam3-tools
sudo chmod +x /usr/local/bin/sam3-tools
Install the darktable plugin:
rm -rf $HOME/.config/darktable/lua/Custom
git clone https://github.com/AyedaOk/DT_custom_script.git $HOME/.config/darktable/lua/Custom
Install the following first
winget install -e --id Microsoft.VCRedist.2015+.x64 --source winget --accept-package-agreements --accept-source-agreements
winget install -e --id Git.Git --source winget --accept-package-agreements --accept-source-agreements
winget install -e --id astral-sh.uv --source winget --accept-package-agreements --accept-source-agreementsAfter installing, close this terminal, reopen PowerShell, and continue with:
cd $env:USERPROFILEClone the repo, create the virtual environment:
git clone https://github.com/AyedaOk/sam3-tools.git
cd sam3-tools
uv venvInstall application:
If your GPU is running CUDA 13, run this command first. You can check your version by running nvidia-smi:
uv pip install --pre --index-url https://download.pytorch.org/whl/nightly/cu130 torch torchvision
uv pip install -r requirements.txtIf you don't have a GPU and want to install it for CPU only:
uv pip install --index-url https://download.pytorch.org/whl/cpu torch torchvision
uv pip install -r requirements.txtOtherwise, run this command:
uv pip install -r requirements.txtSAM3 checkpoints are gated on Hugging Face, so you must request access and log in before first run.
Request access here (wait for approval):
https://huggingface.co/facebook/sam3
Create a Hugging Face access token (token type should be Read):
https://huggingface.co/settings/tokens
Log in from your terminal using the access token:
uv run hf auth loginDownload the model files into the Hugging Face cache:
uv run python -c "from transformers import Sam3Model, Sam3Processor; Sam3Model.from_pretrained('facebook/sam3'); Sam3Processor.from_pretrained('facebook/sam3'); print('SAM3 downloaded into the Hugging Face cache')"Install the Darktable plugin:
Remove-Item "$env:LOCALAPPDATA\darktable\lua\Custom" -Recurse -Force -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\darktable\lua" | Out-Null
git clone https://github.com/AyedaOk/DT_custom_script.git "$env:LOCALAPPDATA\darktable\lua\Custom"Install Homebrew first (skip if you already have brew):
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"If brew is not on your PATH yet, restart your terminal or run:
eval "$(/opt/homebrew/bin/brew shellenv)"Install the following dependencies:
brew update
brew install git uvCreate the installation directory:
mkdir -p "$HOME/Applications"Clone the repo, create the virtual environment and install the Python app:
cd "$HOME/Applications"
git clone https://github.com/AyedaOk/sam3-tools.git
cd sam3-tools
uv venvInstall application:
uv pip install torch torchvision
uv pip install -r requirements.txtSAM3 checkpoints are gated on Hugging Face, so you must request access and log in before first run.
Request access here (wait for approval):
https://huggingface.co/facebook/sam3
Create a Hugging Face access token (token type should be Read):
https://huggingface.co/settings/tokens
Log in from your terminal using the access token:
uv run hf auth loginDownload the model files into the Hugging Face cache:
uv run python -c "from transformers import Sam3Model, Sam3Processor; Sam3Model.from_pretrained('facebook/sam3'); Sam3Processor.from_pretrained('facebook/sam3'); print('SAM3 downloaded into the Hugging Face cache')"The launcher is included in:
sam3-tools/launcher/sam3-tools.commandEdit the cd line to match where you cloned the project.
Example (default install to ~/Applications):
#!/bin/bash
set -e
cd "$HOME/Applications/sam3-tools"
exec "$HOME/Applications/sam3-tools/.venv/bin/python" main.py "$@"Make the launcher executable:
cd "$HOME/Applications/sam3-tools"
chmod +x launcher/sam3-tools.commandNow you can double-click sam3-tools.command in Finder to start the app.
Install the darktable plugin:
rm -rf "$HOME/.config/darktable/lua/Custom"
git clone https://github.com/AyedaOk/DT_custom_script.git "$HOME/.config/darktable/lua/Custom"If builds fail (missing compilers/headers), install Xcode CLT (then re-run):
xcode-select --install