Cellpose: Install, Models (Cellpose-SAM) and CLI Guide

Cellpose is an open-source Python tool that segments cells and nuclei in microscopy images using a pretrained deep-learning model. This guide is for researchers and lab staff who need to get from installation to a mask file: it gives the install commands, a cross-walk of the built-in model names (including Cellpose-SAM), the command-line flags that control a run, the installation fixes the official docs list, and which paper to cite. Commands and flags are as given in the Cellpose documentation (version 4.2.1 documentation) and the project README, read 2026-11-07.

What Cellpose is used for in research

Cellpose is a generalist cell segmentation framework: you give it an image and it returns an integer mask in which each segmented cell or nucleus has its own label. It ships with a graphical interface, a command-line tool and a Python API, and its models can be retrained on your own annotated images. Segmentation output usually feeds downstream measurement such as counting, area and intensity quantification; for the measurement step in ImageJ see quantification in ImageJ for a worked image-analysis procedure, and QuPath for another open image-analysis platform used with microscopy data. For 3D culture imaging context, see organoid.

Cellpose, Cellpose-SAM and the “cell pose” spelling

The tool is one word, “Cellpose”, developed by the MouseLand group. It is often searched as “cell pose”; there is no separate tool by that name. “Cellpose-SAM” (model name cpsam) is the model family introduced in Cellpose 4 that builds on a Segment Anything (SAM) vision-transformer backbone; the docs and README describe it alongside newer DINO-based models.

Install or access (official source only)

The official source is the MouseLand repository (github.com/MouseLand/cellpose) and the documentation at cellpose.readthedocs.io. The README’s recommended route is a conda environment:

1. conda create --name cellpose python=3.12 (the README notes 3.9 and 3.11 also work)
2. conda activate cellpose
3. With the graphical interface: python -m pip install cellpose[gui]. Without it: python -m pip install cellpose. In zsh, quote the extra: 'cellpose[gui]'.

To upgrade later, run python -m pip install cellpose --upgrade. The README also describes a plain virtual-environment route for Python 3.8 or newer, and an optional install of the DINOv3 package (python -m pip install git+https://github.com/facebookresearch/dinov3) for the DINO-based models. Model weights download automatically on first use and are stored in $HOME/.cellpose/models/; set the CELLPOSE_LOCAL_MODELS_PATH environment variable to change that folder (set on Windows, export on Linux, or os.environ before import in a notebook).

GPU notes from the installation page: on Apple Silicon use --use_gpu with an MPS-enabled build; for NVIDIA, install the drivers first; AMD ROCm is documented for Linux only.

Licence note

The README states that all Cellpose models were trained on data under a CC-BY-NC licence and lists the code repository as BSD-3-Clause. Read the repository’s LICENSE file and README before using the models in any setting beyond academic research.

Step-by-step: from image to masks

Option A: graphical interface

1. Activate the environment and start the GUI with python -m cellpose. For 3D stacks use python -m cellpose --Zstack.
2. Open an image, choose a model from the model dropdown, and set the cell diameter if your cells differ from the training size (see below).
3. Run segmentation and inspect the overlay. Masks and annotations can be saved from the GUI.

Option B: command line

The docs list the command as cellpose, and it is also reachable as python -m cellpose. A typical run over a folder:

python -m cellpose --dir /path/to/images --pretrained_model cpdino --diameter 60 --save_tif --savedir /path/to/output

Flags documented on the CLI page:

Flag	What it does (per the docs)
--dir / --image_path	Process every image in a folder, or a single image
--pretrained_model	Model to use; default is cpsam_v2
--diameter	Resizes cells so they match the training diameter of 30 px
--use_gpu, --gpu_device	Run on a GPU and choose which one
--save_tif, --save_png, --no_npy	Choose output file formats
--savedir	Output folder; defaults to the input folder
--output_name	Output name suffix; default _cp_masks
--save_flows, --save_outlines	Also save flow fields or cell outlines
--save_rois	Save ImageJ ROIs
--save_txt, --save_mpl	Save outline text files, or a matplotlib summary figure

Option C: Python API

The models page shows selecting a model in code with models.CellposeModel(pretrained_model='cpdino'). To register a model you trained yourself, run python -m cellpose --add_model /full/path/to/model.

Built-in models: Cellpose-SAM, cpsam_v2 and cpdino

The Models page of the documentation lists these built-in names. Choose one in the GUI dropdown, with --pretrained_model, or in the API.

Model name	What the docs say	Tile size
cpsam_v2	SAM ViT-L based; June 2026 release with a training fix for low-contrast regions; the CLI default	Fixed 256 x 256
cpsam	The original Cellpose-SAM model (April 2025)	Fixed 256 x 256
cpdino	DINOv3 ViT-L based	Default 384 x 384, adjustable with bsize
cpdino-vitb	Smaller DINOv3 variant	Default 384 x 384, adjustable with bsize

Cellpose-SAM tile size is fixed and cannot be changed. The DINO models require the optional DINOv3 install shown above.

Cell diameter

The docs state the models were trained on cells with diameters from 7.5 to 120 px, with a mean of 30 px. For larger cells set diameter explicitly (for example, diameter=60 downsamples the image by 2), and raise niter for large cells.

Output and how to read it

By default the output name suffix is _cp_masks. The mask is an integer image: background is 0 and each segmented object carries its own positive label, so the maximum label is the object count. Use --save_tif or --save_png for image files, --save_rois to open the cells as ImageJ ROIs, and --save_outlines or --save_flows when you need to check the boundaries. The suffix _seg.npy is the annotation format the GUI writes for training with --mask_filter. Always overlay masks on the raw image and spot-check before measuring.

Troubleshooting

These fixes are listed on the official installation page.

Symptom	Documented fix
GUI will not start on Linux (Qt xcb error)	sudo apt install libxcb-cursor0 libxcb-xinerama0
No module named PyQt5.sip	Uninstall and reinstall pyqt5, pyqt5-tools and pyqt5.sip
libiomp5 error	conda install nomkl
matplotlib error	pip install matplotlib --upgrade
_arpack DLL error	Reinstall scipy

Free alternatives and ways to run Cellpose

Tool	Relationship to Cellpose (source)
ImageJ / Fiji	The ImageJ documentation has a Cellpose page: Cellpose is a Python package, and several options exist to run it from Fiji (imagej.net/plugins/cellpose, read 2026-11-07)
Cellpose GUI	Built in; installed with cellpose[gui] (README)

Which paper to cite

The README lists: Cellpose 1.0, Stringer et al. 2021, Nature Methods 18(1):100-106 (cite it for Cellpose 1, 2 and 3 usage); Cellpose 2.0, Pachitariu and Stringer 2022, Nature Methods; Cellpose3, Stringer and Pachitariu 2025, Nature Methods; Cellpose-SAM, Pachitariu, Rariden and Stringer 2025, bioRxiv. Also record the software version and model name you used so the analysis can be reproduced.

FAQ

What is Cellpose-SAM?

Cellpose-SAM is the Cellpose 4 model family built on a Segment Anything backbone; its built-in names are cpsam and cpsam_v2, both using fixed 256 x 256 tiles.

Does Cellpose need a GPU?

The docs describe GPU use through --use_gpu for NVIDIA, Apple Silicon (MPS) and AMD (ROCm, Linux only); the flag is optional.

Which model is the default?

The CLI documentation gives cpsam_v2 as the default for --pretrained_model.

Where does Cellpose store model weights?

In $HOME/.cellpose/models/ unless CELLPOSE_LOCAL_MODELS_PATH is set.

Sources

• Cellpose README, github.com/MouseLand/cellpose (read 2026-11-07)
• Cellpose documentation: Models, Command line, Installation, cellpose.readthedocs.io (version 4.2.1 documentation, read 2026-11-07)
• ImageJ documentation, Cellpose, imagej.net/plugins/cellpose (read 2026-11-07)