Deepo: generating custom deep learning Docker images from Lego-like modules

What Deepo solves for people who keep rebuilding CUDA environments

Installing several deep learning frameworks in one environment is mostly a dependency problem. CUDA, cuDNN, the Python version and each framework's wheel all constrain one another, and the installation order matters. Deepo's README describes it as an open framework for assembling specialized Docker images, with a Dockerfile generator at its core. The generator is the part that does the work: according to the README, Deepo knows which combinations of CUDA, cuDNN, Python, PyTorch and TensorFlow are compatible, picks the right versions, and determines the installation order by topological sorting.

The intended audience is a researcher or engineer who wants a working environment in one command rather than an afternoon of version archaeology. The README frames the pre-built images as a way to instantly set up common research environments, with tags for individual frameworks and an all-in-one image containing every supported framework. GPU acceleration via CUDA and cuDNN is included, and the same images run in CPU-only mode on Linux, Windows and macOS.

How the generator and the pre-built images differ

There are two distinct products here, and conflating them causes confusion. The first is a set of images published on Docker Hub under ufoym/deepo. Pulling ufoym/deepo gives you the standard image containing every available framework; appending a framework name as a tag, for example ufoym/deepo:tensorflow, gives you a single-framework image. These are fixed artifacts. Whatever versions were baked in when the image was published is what you get.

The second product is the generator, which lives in the generator/ directory of the repository. You clone the repository, run generate.py with a list of modules, and it writes a Dockerfile. The README states the generator follows best practices, resolves dependencies automatically, and sorts installation steps topologically. That is the mechanism: modules in, dependency graph resolved, ordered Dockerfile out. You then build that Dockerfile yourself, so you control the build and can inspect exactly what goes into the image. The trade-off is that the generator's knowledge of compatible version combinations is only as current as the repository, and the newest release listed is v2.0.0 from 2017-11-27.

Pulling the all-in-one image and checking GPU access

The GPU path starts with Docker and the NVIDIA Container Toolkit, which the README lists as prerequisites. Then pull the image and verify that the container can see the GPU before you do anything else.

docker pull ufoym/deepo
docker run --gpus all --rm ufoym/deepo nvidia-smi

If nvidia-smi does not produce output, the README points to the issues section of the NVIDIA Container Toolkit GitHub, noting that many solutions are already documented there. That is a reasonable first stop, and it also tells you the failure is usually in the host driver or toolkit rather than in the image. To get an interactive shell in a container you can keep using:

docker run --gpus all -it ufoym/deepo bash

The CPU variant follows the same shape with a different tag. The README's CPU install is docker pull ufoym/deepo:cpu, and the interactive shell is docker run -it ufoym/deepo:cpu bash. Once inside, the README's own verification is a Python session that imports tensorflow, torch, keras, mxnet, chainer and paddle, plus a darknet command that prints its usage line.

Mounting data, shared memory, and Jupyter Lab on port 8888

Two runtime details matter more than they look. The first is volume mounting. The README's example maps /host/data to /data and /host/config to /config with -v, and states that this isolation helps prevent containerized experiments from accidentally overwriting or reading the wrong data. If you skip it, work inside the container disappears when the container does.

docker run --gpus all -it -v /host/data:/data -v /host/config:/config ufoym/deepo bash

The second is shared memory. The README warns that some frameworks, PyTorch among them, use shared memory for inter-process communication, and that the container default may be too small when you use multiprocessing. The suggested fixes are --ipc=host or --shm-size. For interactive work, the README's Jupyter recipe runs Jupyter Lab on port 8888 with the host home directory mounted at /root:

docker run --gpus all -it -p 8888:8888 -v /home/u:/root --ipc=host ufoym/deepo jupyter lab --no-browser --ip=0.0.0.0 --allow-root --LabApp.allow_origin='*' --LabApp.root_dir='/root'

Note the combination of --allow-root and a wildcard allowed origin. That is workable on a trusted machine or an isolated network, and I would not expose that port on a shared host without changing the origin setting.

Building a custom image with pytorch and keras

This is where the generator earns its place. Clone the repository and move into the generator directory:

git clone https://github.com/ufoym/deepo.git
cd deepo/generator

Then describe the environment on one command line. The README's example creates an image with pytorch and keras:

python generate.py Dockerfile pytorch keras

The first argument is the output path, and the rest are modules. CUDA and cuDNN versions can be pinned, and the README shows --cuda-ver 11.3.1 --cudnn-ver 8 as an example. The Python version can be pinned too, with a module of the form python==3.8. After generation, build it:

docker build -t my/deepo .

The README notes this may take several minutes, which is unsurprising for an image that installs CUDA and multiple frameworks. Read the generated Dockerfile before building. Since the generator resolves versions on your behalf, the file is the only place where you can see which ones it chose.

Where Deepo stops being the right tool

The clearest limitation is age. The releases listed for this repository are v1.0.0 and v2.0.0, both dated 2017-11-27. The README's own examples reference CUDA 11.3.1 and cuDNN 8, which suggests the generator configuration has been touched since then, and the repository's last push was on 2026-03-25. But the release history gives you no versioned, dated artifact to reason about, so pinning Deepo to a specific release is not really possible.

That matters if your work depends on a framework feature added after the generator's compatibility table was written. In that case the automatic dependency resolution becomes a constraint rather than a convenience, because the generator will pick from the combinations it knows. A second limitation is scope: these are research environments, not deployment images. Nothing in the README describes a hardened runtime, a non-root user, or a reduced image for serving. If you need a small production image, an all-in-one research container is the wrong starting point. Finally, the generator writes a Dockerfile. If your team builds with a different tool, you are adopting a build step that produces input for your existing pipeline, which may or may not be worth it.

Alternatives and how their approach differs

The obvious alternative is to write the Dockerfile yourself from an official base image, for example a CUDA base image from NVIDIA or a framework's own published image. That approach gives you exact control over every layer and every version, and it stays current as long as you update it. What you give up is the dependency resolution: you are the one who has to know that this cuDNN build matches that CUDA runtime and that this framework wheel is built for that Python version. Deepo's value proposition is precisely that it holds that knowledge in one place.

A second alternative is a package manager that resolves the same problem at the Python level, such as conda environments. The difference in approach is the boundary. Conda resolves Python packages inside whatever operating system and CUDA installation you already have, so the host still has to match. Deepo resolves at the container level, which means the CUDA runtime, cuDNN and the frameworks are all decided together and shipped as one artifact. That is stronger isolation and a heavier artifact. Neither is universally better; they fail in different places.

Licence, upgrade cost, and what to check before you commit

The repository is MIT licensed, and the README has a Licensing section of its own. MIT is permissive, so using the generator and the Dockerfiles it produces in commercial work is not something the licence appears to restrict. This is a description of the licence text, not legal advice; if your organisation has rules about bundled binaries, note that the images contain CUDA and cuDNN, whose own terms come from NVIDIA rather than from this repository.

The upgrade cost is the part to think about honestly. Because the generator picks versions for you, moving to a newer CUDA or a newer framework means either waiting for the compatibility table to be updated or overriding versions with flags such as --cuda-ver and --cudnn-ver and accepting that the resolved combination is no longer one the generator vouched for. There is no documented migration path between releases in the README, and with the newest release dated 2017-11-27 there is little release-level guidance to follow. Before adopting it, pull the tag you actually need and run the nvidia-smi check on your host, generate a Dockerfile for your exact module list, and read it. That file tells you more about what you are getting than any tag name does.

Editorial conclusion

Adopt Deepo if you want a working deep learning environment on a Linux GPU host or a CPU-only laptop without resolving CUDA and framework compatibility yourself, or if you need to generate a Dockerfile for a specific combination such as pytorch plus keras. Do not adopt it if you need current framework releases or a vendor-supported stack, because the newest release in the repository is v2.0.0 from 2017-11-27. Before committing, run the GPU check command on your host, confirm the tag you need exists on Docker Hub, and read the generated Dockerfile after running generate.py so you know which versions you are actually building on.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. ufoym/deepo on GitHub