Cellpose

4.1.1 verified Fri May 01 auth: no python

Cellpose is a deep learning-based anatomical segmentation algorithm for cells and nuclei, developed by Carsen Stringer and Marius Pachitariu. The current version is 4.1.1 (as of early 2025). Release cadence is active with several minor versions per year.

pip install cellpose

Common errors

error AttributeError: module 'cellpose.models' has no attribute 'Cellpose' ↓

cause Cellpose v4 removed the Cellpose class. Users try to import Cellpose as in v3.

fix

Use from cellpose.models import CellposeModel and instantiate CellposeModel.

error RuntimeError: expected scalar type Half but found Float ↓

cause Mixing float and half precision (bfloat16) on GPU, often because model weights are bfloat16 but input tensor is float32.

fix

Set model = CellposeModel(gpu=True, model_type='cyto') to automatically match precision, or convert input: img = img.to(torch.bfloat16).

error ValueError: channels must be a list of two integers ↓

cause `channels` parameter passed as a single integer or None, which is no longer supported in v4.

fix

Use channels=[0,0] for grayscale, or channels=[0,1] for two-channel images.

error ModuleNotFoundError: No module named 'cellpose.denoise' ↓

cause The denoise module was removed in Cellpose v4.

fix

Use Cellpose 3.x for denoising, or apply external denoising libraries.

Warnings

breaking Cellpose v4 drops the `Cellpose` class and `SizeModel`. Users must use `CellposeModel` for all segmentation. ↓

fix Replace `from cellpose.models import Cellpose` with `from cellpose.models import CellposeModel`.

breaking Cellpose v4 does not include the denoise module (`cellpose.denoise`). ↓

fix For denoising, use Cellpose 3.x or alternative methods.

deprecated `channels` parameter now expects a list of two integers (channel index, second channel). Passing `None` or single int is deprecated. ↓

fix Use `channels=[0,0]` for single-channel grayscale images.

gotcha MPS (Apple Silicon) backend may produce incorrect results with certain operations (e.g., bfloat16). ↓

fix Set `torch.backends.mps.is_available()` carefully and consider using CPU or CUDA if artifacts appear.

gotcha Cellpose models trained in v3.x are not fully compatible with v4.x without retraining. ↓

fix Retrain your model using the `CellposeModel` API in v4, or stick to v3 for existing models.

Imports

CellposeModel
wrong
```
from cellpose.models import Cellpose
```
correct
```
from cellpose.models import CellposeModel
```
Cellpose class removed in v4.0.0; use CellposeModel instead
models
```
from cellpose import models
```
io
```
from cellpose import io
```

Quickstart

Loads a pretrained cyto model and segments a random image.

import numpy as np
from cellpose.models import CellposeModel
model = CellposeModel(gpu=True, model_type='cyto')
img = np.random.rand(256, 256).astype(np.float32)
mask, flow, style = model.eval(img, channels=[0,0], diameter=30.0)
print(mask.shape)