deepcell-tf: TensorFlow Models for Cell Segmentation and Tracking
Deep Learning Library for Single Cell Analysis
At a glance
- What is it?
- deepcell-tf packages pre-trained TensorFlow 2 models for 2D and 3D cell segmentation and 2D time-lapse tracking, alongside annotated datasets. The library is aimed at imaging scientists who need working segmentation without building a model from scratch, and the main constraint is that it expects pixel scaling to match the training data.
- Who is it for?
- Adopt deepcell-tf if you work with fluorescent nuclear or phase/fluorescent whole-cell images in 2D or 3D and want pre-trained models plus annotated datasets in one package. Do not adopt it if your images are tissue-level, multiplexed, or captured at a pixel size far from the training data, because the documentation itself flags tissue models as unfinished work.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 104 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap deepcell-tf fills between raw microscopy and usable cell counts
Segmentation of biological images has traditionally been done with thresholding or watershed, which works until cells touch, vary in brightness, or sit in a 3D stack where the z-axis confounds a 2D filter. deepcell-tf addresses that by shipping pre-trained neural networks for two specific tasks: whole-cell and nuclear segmentation in 2D and 3D images, and cell tracking in 2D time-lapse datasets. The README states the models apply to data ranging from multiplexed images of tissues to dynamic live-cell imaging movies, though it also notes that tissue data and models are still being expanded.
The intended user is a biologist or imaging scientist who has data and needs masks or tracks, not a machine learning engineer looking for a model zoo to fine-tune. The README describes two modules that carry most of the practical weight: deepcell.datasets, a collection of annotated biological images, and deepcell.applications, which holds the pre-trained models. The datasets module includes live-cell imaging movies of fluorescent nuclei (approximately 10,000 single-cell trajectories over 30 frames) and static whole-cell images in phase and fluorescence (approximately 75,000 single-cell annotations). Those numbers describe the shipped training data, not the library's user base.
If your question is "which pixels belong to which cell" and you have a GPU, this library is a direct answer. If your question is "what is the transcriptional state of this cell," it is not; deepcell-tf stops at the mask and the track.
How the applications and datasets modules actually fit together
The architecture visible in the README is a two-layer split. The lower layer is TensorFlow 2: the library is written in Python and built on TF2, so model definitions, training loops, and weight files live in that ecosystem. The upper layer is a set of application wrappers that bundle a model with the preprocessing and postprocessing needed to turn an image into an instance segmentation or a lineage. The documentation points to deepcell.applications as the entry point for inference and to deepcell.datasets as the source of annotated training data.
Around the core library sits a wider ecosystem, and this matters for anyone planning a pipeline. The README names four sibling projects: DeepCell Toolbox for pre- and post-processing model outputs, DeepCell Tracking for building cell lineages with deep-learning-based tracking models, DeepCell Kiosk for deploying workflows on large datasets in the cloud, and DeepCell Label for annotating high-dimensional images to use as training data. The README also warns that the datasets and applications modules may be spun off into their own GitHub repositories in the near future. That is a real integration risk: code that imports from deepcell.datasets today may need a different import path later.
Data flow for a tracking run, as described, is sequential: raw time-lapse frames go into a segmentation model, the resulting per-frame masks go into a tracking model, and the output is a set of single-cell trajectories. The README's example table shows a raw image next to a tracked image, which is the visual form of that pipeline. Nothing in the supplied material describes the internal network architecture, so any claim about backbone choice or loss function would be speculation.
Installation paths: pip, Docker, and the CUDA requirement
The fastest documented route is a single pip install:
pip install deepcell
That gets you the library on CPU. For GPU work the README offers a Docker image on DockerHub under vanvalenlab/deepcell-tf, and states that you need CUDA plus Docker v19.03 or later. For older Docker versions the README points to nvidia-docker. The documented run command is:
docker run --gpus '"device=0"' -it --rm -p 8888:8888 -v $PWD/notebooks:/notebooks -v $PWD/data:/data vanvalenlab/deepcell-tf:latest-gpu
Two details in that command are easy to miss. First, the volume mounts for /notebooks and /data are not optional conveniences: the README states that data and models must be saved in these mounted directories to persist them outside of the running container. Second, the container starts a Jupyter session on port 8888, which you can remap with -p 8080:8888 or any non-reserved port.
For developers building from source, the README says deepcell-tf uses docker and tensorflow to enable GPU processing, and that the local container build takes a TensorFlow version specified through the TF_VE variable. The README excerpt cuts off mid-sentence at that point, so the exact syntax of the build step is not confirmed here. What is confirmed is that TensorFlow version selection is a build-time parameter, which means the TF version is pinned by the image rather than floating. The README also links two training notebooks, one for segmentation and one for tracking, for anyone moving past inference.
The pixel-scaling constraint is the failure mode to plan around
The README is unusually direct about the condition for out-of-the-box use: provided data is scaled so that the physical size of each pixel matches that in the training dataset, the models can be used on live-cell imaging data. Read that as a hard prerequisite rather than a suggestion. A model trained on images at one micron-per-pixel will not transfer cleanly to images at a very different sampling density, because cell size in pixels changes while the network's receptive field does not. If your microscope, binning setting, or objective differs from the training configuration, you are in retraining territory, and the library gives you the datasets and notebooks to do that but not a shortcut around it.
The second limitation is scope. The README says the team is currently working to expand the datasets and applications modules to include data and models for tissue images. That sentence tells you tissue segmentation is not a solved path in this release. The README mentions multiplexed tissue images as a domain the models are applicable to, but the same paragraph marks tissue models as unfinished. Anyone whose primary data is tissue-level should treat that as a gap, not a roadmap promise.
The third issue is version drift. The most recent release listed is 0.12.10 from August 2024, with 0.12.9 and 0.12.8 both landing in 2023. The repository shows a push in June 2026, which suggests ongoing work, but the release cadence is not fast. Because the library is built on TensorFlow 2, a pinned TF version in the Docker image is doing real work: upgrading TF independently of the image risks breaking the model wrappers. Treat the container as the supported configuration and the pip install as the convenience path.
Cellpose as the alternative, and where the two diverge
The obvious comparison is Cellpose, the generalist cell segmentation model that many imaging labs reach for first. The difference in approach is the shape of the offering. Cellpose is primarily a segmentation tool with a graphical interface and a Python API, oriented around getting masks from a broad range of image types with minimal setup. deepcell-tf is a TensorFlow 2 library that pairs pre-trained models with its own annotated datasets and a training path, so the intended workflow includes retraining on your own annotations when the pre-trained model does not fit.
That distinction drives the adoption decision. If you need masks today from fluorescence images and you never intend to train, a single-purpose segmentation tool will get you there with less surface area. If you need segmentation plus tracking in one ecosystem, or you want the annotated nuclear and whole-cell datasets that ship with deepcell-tf to bootstrap your own model, the library's breadth is the reason to pick it. The README's ecosystem framing reinforces this: Toolbox, Tracking, Kiosk, and Label are separate projects, each covering a stage that a generalist segmentation tool would leave you to solve with other software.
The cost of that breadth is more moving parts. A deepcell-tf pipeline can involve the core library, a Docker image with a pinned TF version, and potentially the Toolbox or Tracking packages for post-processing and lineage construction. Each is a separate install and a separate version to track. Cellpose's narrower scope is also its advantage when all you want is a mask.
Licence and the maintenance arithmetic
The repository lists Apache-2.0 as its license, while the README badge reads Modified Apache 2.0 and links to the LICENSE file. Those two labels are not identical, and the modification is the part that matters. Anyone embedding deepcell-tf in a commercial product or a hosted service should read the LICENSE file directly rather than relying on the badge text, and should route the question to their own counsel. Nothing here is legal advice, and the supplied material does not spell out what the modification adds.
On maintenance, the arithmetic is straightforward. The last release in the supplied list is 0.12.10 from August 2024. The repository shows a push in June 2026, so the project is not abandoned, but a gap of that length between a tagged release and current activity means you should not expect frequent version bumps. The practical consequence is that your dependency resolution will likely pin a specific TensorFlow 2 minor version for a long time. Budget for that in your environment files.
The README's note that deepcell.datasets and deepcell.applications may be spun off into their own repositories is the other maintenance item. A future split would change import paths, so any wrapper code you write around those modules should be thin. Two notebooks are linked for training a segmentation model and a tracking model, and those are the best starting point for judging whether the retraining path is one your team can maintain.
Editorial conclusion
Adopt deepcell-tf if you work with fluorescent nuclear or phase/fluorescent whole-cell images in 2D or 3D and want pre-trained models plus annotated datasets in one package. Do not adopt it if your images are tissue-level, multiplexed, or captured at a pixel size far from the training data, because the documentation itself flags tissue models as unfinished work. Before committing, verify that your pixel-to-micron scaling matches the training data, check which TensorFlow version your installed deepcell release pins, and confirm whether the datasets and applications modules have moved to their own repositories as the README anticipates.
Community notes