# vanvalenlab/deepcell-tf: you install deepcell, and the notebook server runs as root

> A TensorFlow 2 library for single-cell segmentation and tracking on biological images, distributed on PyPI under the shorter name deepcell. The pinned TensorFlow major minor line is two releases old, the Docker build tags one image name while the documented run command expects another, and the notebook entry point binds every interface with root allowed.

**vanvalenlab/deepcell-tf** — Deep Learning Library for Single Cell Analysis

- Repository: https://github.com/vanvalenlab/deepcell-tf
- Website: https://deepcell.readthedocs.io
- Stars: 481 · Forks: 110
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/vanvalenlab-deepcell-tf

## The repository is deepcell-tf and the package you install is deepcell

The install instruction is a single line:

```bash
pip install deepcell
```

The distribution name is not the repository name. The repository, the module path inside it and the container image are all called deepcell-tf, while the PyPI project the badges point at, including the package statistics badge, is `deepcell`. So the pip name and the import name differ by a suffix, and anyone scripting an install has to know which one to use. The badges themselves are pinned to the master branch rather than the default branch name used elsewhere in the ecosystem, which for this repository happens to be the same thing but makes the coupling to that branch explicit in every link at the top of the file. The README also opens with a level-one heading that contains no text at all, so the raw file begins with a bare hash character.

## Package metadata is obtained by executing a file at build time

The packaging file does not contain the package identity. Instead it opens the module's version file, reads its contents into a dictionary using the built-in execution facility, and then pulls the name, version, author, author email, description, url, download URL and licence out of that dictionary to feed the setup call. Everything that identifies the published artifact therefore lives in a small Python file inside the package rather than in the packaging script itself. The effect is that reading setup.py tells you nothing about what version you would install, and a mistake in the version file is a build-time execution failure rather than a validation error. There is also a second configuration file alongside it that carries only build requirements and lint settings, with no project table, so the two files split configuration in a way that is easy to miss.

## TensorFlow is pinned to a single minor line and the addons package is finished

The dependency list holds TensorFlow at a compatible-release pin of 2.8.0, which admits only the 2.8 series, and TensorFlow Addons at a matching narrow range. The declared interpreter support is 3.7 through 3.10. Those two facts intersect in a small band, because TensorFlow 2.8 predates Python 3.11 support, so a machine on 3.11 satisfies the declared range while being unable to satisfy the TensorFlow pin. The addons dependency compounds this: that package was a community extension for TensorFlow versions that predate the built-in equivalents and is no longer being developed, so the install depends on a library whose ecosystem has moved on. The release record reinforces the age. The most recent tagged release is 0.12.10 from August 2024, the one before it is from September 2023, and the default branch was last pushed in June 2026, so published artifacts trail the branch by roughly two years.

## The build tags one image name while the run command expects another

The developer workflow is two documented commands, and they do not agree with each other. The build is:

```bash
git clone https://github.com/vanvalenlab/deepcell-tf.git
cd deepcell-tf
docker build --build-arg TF_VERSION=2.8.0-gpu -t $USER/deepcell-tf .
```

The image name given there carries no tag, so it resolves to the default latest tag. The run command that follows references the same name with an explicit GPU suffix:

```bash
# '"device=0"' refers to the specific GPU(s) to run DeepCell-tf on, and is not required
docker run --gpus '"device=0"' -it \
-p 8888:8888 \
$USER/deepcell-tf:latest-gpu
```

Running these two as written in sequence fails to find the image, since nothing in the build produces a tag matching the one the run command asks for. The prebuilt image published for general use does carry that suffix, which is what makes the mismatch easy to miss. A second wrinkle sits underneath: the documentation notes that you must run the image once without mounting a local copy of the repository, so compiled extensions can be built inside the container and then copied across, which means the editable-mount shortcut does not work on a first run.

## The notebook entry point binds every interface and permits root

The container's default command starts a Jupyter Lab server bound to all network interfaces with the flag that permits running as root, and the documented run commands publish that port straight through to the host with a plain port mapping. A notebook server reachable on every interface, running as root inside the container, is the combination to be careful with, particularly because the notebook port is the main user-facing surface of the GPU image and the docs suggest changing its host-side number casually. Mitigating this is the fact that the port mapping is a host-to-container binding rather than a published registry port, so the exposure depends entirely on the host's own network configuration and on whether a token is supplied. The documentation does not mention passing a token or a password, which is the setting that would remove the concern.

## The image is built from an end-of-life CUDA key path

The base image is parameterised by a build argument defaulting to a GPU build of TensorFlow 2.8.0, and the next step fetches a CUDA signing key directly from NVIDIA's repository path for Ubuntu 18.04 using the legacy key-advancing command, with an inline link to an NVIDIA forum post about that repository rotating its key. Ubuntu 18.04 is past its standard support window and the key tool it uses has been superseded, so this step is the most date-sensitive line in the build. Later steps install Graphviz, upgrade pip, copy the packaging files into an image directory, and install the package. Notably, the install step first edits the requirements file with a substitution intended to strip the TensorFlow entry so the base image's copy is not replaced, and the expression it uses looks for a character that the pinned requirement line does not actually contain, so the removal is narrower than its comment claims.

## An undefined-name lint error is knowingly suppressed

The lint configuration is unusually candid about accumulated debt, because each suppression carries a comment naming an issue. The file to which an undefined-name rule is switched off is annotated as awaiting a resolution and refers to an issue number. Another entry suppresses the same rule pending either adding tests or deleting a file, and a third relaxes an import-order rule because of a circular import, again with an issue reference. One suppression is marked as expiring and refers to a deprecation. The selected rule set is a small modern subset covering style, errors and upgrades, notebooks are excluded from linting entirely, and per-file exemptions are also granted to package initialisers so that unused and star imports pass. The target interpreter version for the linter is a much older one than the newest the package supports, so modernisation checks are run against the oldest supported syntax.

## Two requirement lists disagree, and Jupyter is a runtime dependency

The project ships both a requirements file and an install-requires block, and they are not the same list. One declares a notebook package with a bounded range while the other names a different notebook distribution unversioned, and the headless OpenCV binding appears in only one of them. The generated options schema and lint tooling are at least confined to an extras group, which is the right place for them. The notebook dependency is not, which means a library install pulls a notebook stack onto machines that will never open one. One other entry is narrower than it looks: a graph-description package is required specifically so a model-plotting helper in the deep learning framework works. Finally, the developer section of the README breaks off mid-word while describing how to detach from the running container, and the applications section notes that its two modules may be spun out into separate repositories, so the current package layout is described as provisional.

## Conclusion

This suits a lab already committed to the DeepCell ecosystem and to a TensorFlow generation old enough to match the pin. Verify the interpreter and TensorFlow combination before installing, since the declared range and the dependency range only overlap in a narrow band, and do not expose the container's notebook port to a network you do not control. Treat the two bundled requirement lists as one source of truth to reconcile yourself.

## FAQ

### How does DeepCell work?

It is a Python library built on TensorFlow 2 that applies pre-trained models to biological images and can also train new ones. It specialises in whole-cell and nuclear segmentation in 2D and 3D, and in cell tracking over 2D time-lapse data, applying to multiplexed tissue images and live-cell imaging movies.

### How do I install deepcell-tf?

The package is published as `deepcell`, so run `pip install deepcell`. The repository, the importable module and the container image are all named deepcell-tf, so the pip name and the import name differ. GPU use is served by a container image on DockerHub rather than by a separate pip install.

### What TensorFlow and Python versions does deepcell-tf support?

The dependency list pins TensorFlow to the 2.8 series with a compatible-release constraint and TensorFlow Addons to a matching narrow range, while the declared interpreter support is 3.7 through 3.10. The newest tagged release is 0.12.10 from August 2024 and the default branch was last pushed in June 2026.

### How do I run the GPU container for deepcell-tf?

Publish port 8888, mount a notebooks folder and a data folder from the working directory, and start the GPU image, which launches a notebook session on the default port. You need CUDA and Docker 19.03 or later, and data and models must be written into the mounted directories to survive the container. The README also notes that the documented build and run commands use different image tags.

### What datasets and pre-trained models does deepcell-tf bundle?

One module holds annotated biological images including live-cell movies of fluorescent nuclei with roughly 10,000 single-cell trajectories over 30 frames and static whole-cell images with roughly 75,000 annotations. The other holds pre-trained fluorescent nuclear and whole-cell models, with data scaled so the physical pixel size matches the training set so they can be used without adjustment. Both modules may be moved into separate repositories.

## Sources

- [License: Apache-2.0](https://github.com/vanvalenlab/deepcell-tf/blob/master/LICENSE)
- [Project website](https://deepcell.readthedocs.io)
- [README](https://github.com/vanvalenlab/deepcell-tf/blob/master/README.md)
- [Releases](https://github.com/vanvalenlab/deepcell-tf/releases)
- [vanvalenlab/deepcell-tf on GitHub](https://github.com/vanvalenlab/deepcell-tf)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vanvalenlab-deepcell-tf