[Docker] Simplify and modernize Dockerfile by deruyter92 · Pull Request #3290 · DeepLabCut/DeepLabCut

deruyter92 · 2026-04-21T13:56:05Z

This PR is part 1 of updating the docker setup and only entails the Dockerfiles and how we build them. The deeplabcut-docker is also updated, but that is discussed separately in PR #3291 to avoid mixing topics.

adresses #3282, #3285

Motivation

Currently we have many dockerfiles with overlapping (or functionally identical) purpose. This PR replaces that with a single Dockerfile, which is easier to maintain and more transparent for users.
This PR simplifies the variety of image tags to a plain latest, latest-jupyter and 3.0rc14-core-cuda12.4 or similar.
- cuda12.4 is kept as default which should run on basically most machines from the last 5 years (including newer ones thanks to backward compatibility).
- Older DeepLabCut (pre-)releases remain on DockerHub with the appropriate tag.
- <cudnn_version> is dropped from the name, since all were using the same.
- base is dropped as image version since it is equivalent to core.
- cuda 12.1 is dropped as default, and cuda11.8 will remain on DockerHub to support those with legacy hardware.
Images were not strictly matching the PyPI versions. This is changed in this PR for transparency.
Building docker images was done via (somewhat fragile) shell scripts. This PR replaces that with CI-friendly builds using Docker bake / buildx
The tools for Dockerfiles (targeting Docker users) and the deeplabcut-docker package (for deeplabcut-docker developers) was not clearly separated. The package is now moved to its own subdirectory.

Changes

Single multi-stage docker/Dockerfile: replaces separate Dockerfile.base / core / jupyter / test.
Versioned tags like {version}-core-cuda{CUDA} (no cudnn suffix in bake tags).
pip install "deeplabcut[modelzoo,wandb]==${DEEPLABCUT_VERSION}" instead of git main
Buildx bake defines core + jupyter, shared build-args
MARK_LATEST parameter to flag optional latest / latest-jupyter tag.
docker/docker-bake.hcl instead of docker/build.sh
move deeplabcut-docker package to its own subdirectory, separating it from the dockerfile logic.

Not included:

optional: add CI workflow for building docker images on release (should be easy to add now). Can be added in a separate PR.

…iple dockerfiles

Copilot

Pull request overview

This PR modernizes the Docker build setup by consolidating multiple Dockerfiles into a single multi-stage docker/Dockerfile, replacing the legacy docker/build.sh matrix with a CI-friendly docker buildx bake configuration, and relocating the deeplabcut-docker helper package into docker/package/.

Changes:

Replace Dockerfile.base/core/jupyter/test with a single multi-stage docker/Dockerfile (core/jupyter/test stages).
Add docker/docker-bake.hcl to define reproducible build targets/tags (including optional latest tags via MARK_LATEST).
Move/add packaging scaffolding for deeplabcut-docker into docker/package/ and update Docker documentation accordingly.

Reviewed changes

Copilot reviewed 10 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docker/package/setup.cfg	Introduces setuptools packaging metadata + console entry point for `deeplabcut-docker`.
docker/package/pyproject.toml	Defines build backend/requirements for the helper package.
docker/package/deeplabcut_docker.sh	Adds shell launcher that pulls/builds user-mapped images and runs containers.
docker/package/deeplabcut_docker.py	Adds Python CLI wrapper that spawns the shell launcher via a PTY.
docker/package/Makefile	Updates README source path for PyPI packaging workflow.
docker/package/MANIFEST.in	Ensures package artifacts (README/license/script) are included in builds.
docker/package/LICENSE	Adds LGPLv3 license text for the helper package distribution.
docker/docker-bake.hcl	Adds buildx bake targets for core + jupyter with versioned and optional latest tags.
docker/build.sh	Removes legacy bash build/test/push matrix.
docker/README.md	Updates docs for new tags and buildx bake workflow.
docker/Dockerfile.test	Removes old dedicated test Dockerfile (replaced by multi-stage Dockerfile).
docker/Dockerfile.jupyter	Removes old jupyter Dockerfile (replaced by multi-stage Dockerfile).
docker/Dockerfile.core	Removes old core Dockerfile (replaced by multi-stage Dockerfile).
docker/Dockerfile.base	Removes old base Dockerfile (replaced by multi-stage Dockerfile).
docker/Dockerfile	Adds new multi-stage Dockerfile implementing core/jupyter/test stages.
docker/.dockerignore	Adds docker build context ignore rules for a slimmer build context.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

C-Achard

Looks great, very nice consolidation !

Most comments below are about changing existing behavior rather than improving the layout, and may have been handled elsewhere; please filter accordingly.

…n README.md

deruyter92

Thanks @C-Achard, see my response below! Mostly accepted all suggestions, thanks for the helpful review!

* update deeplabcut_docker: replace shell script with pure python * update deeplabcut_docker: modernize setup via pyproject.toml * update deeplabcut_docker README * docker: fix default user home directory -> home/{user} * deeplabcut-docker: update print statement passw->token * deeplabcut-docker: update pyproject.toml Python range 3.10-3.12

MMathisLab

:)

deruyter92 added 5 commits April 21, 2026 15:14

move deeplabcut-docker package to separate subdirectory

9f0ff5d

update dockerfile: add single clean dockerfile that replaces the mult…

26ea5b6

…iple dockerfiles

docker: replace build script with docker bake buildx hcl file

a80e426

add dockerignore file

0748560

docker update README: new dockerfile naming and buildx commands

7547079

deruyter92 mentioned this pull request Apr 21, 2026

[Docker 2] update deeplabcut-docker package #3291

Merged

deruyter92 marked this pull request as ready for review April 21, 2026 14:31

deruyter92 requested a review from Copilot April 21, 2026 14:31

Copilot started reviewing on behalf of deruyter92 April 21, 2026 14:32 View session

Copilot AI reviewed Apr 21, 2026

View reviewed changes

Comment thread docker/Dockerfile Outdated

Comment thread docker/Dockerfile Outdated

Comment thread docker/README.md Outdated

deruyter92 and others added 3 commits April 21, 2026 17:27

Update docker/README.md

04646e6

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docker/Dockerfile

99d31cd

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update dockerfile: fix pretrained weights directory permission

ead4b7c

deruyter92 mentioned this pull request Apr 21, 2026

deeplabcut-docker notebook throws permission error #3285

Closed

2 tasks

deruyter92 requested review from C-Achard April 22, 2026 09:39

C-Achard approved these changes Apr 23, 2026

View reviewed changes

Comment thread docker/docker-bake.hcl

Comment thread docker/Dockerfile

Comment thread docker/Dockerfile

Comment thread docker/Dockerfile Outdated

Comment thread docker/Dockerfile

C-Achard assigned deruyter92 Apr 28, 2026

C-Achard added the Docker label Apr 28, 2026

deruyter92 added 3 commits April 28, 2026 17:18

dockerfile: add healthcheck for jupyter exposed port

ff549d1

dockerfile: add override jupyter token option + port-expose warning i…

8d45764

…n README.md

dockerfile: add comment regarding root-user

b73c99f

deruyter92 commented Apr 28, 2026

View reviewed changes

Comment thread docker/Dockerfile

Comment thread docker/Dockerfile

Comment thread docker/Dockerfile Outdated

Comment thread docker/Dockerfile

C-Achard approved these changes Apr 29, 2026

View reviewed changes

This was linked to issues May 5, 2026

deeplabcut-docker notebook throws permission error #3285

Closed

Simplify and modernize DeepLabCut Docker images and build pipeline #3282

Closed

deruyter92 requested review from AlexEMG and MMathisLab May 6, 2026 09:00

deruyter92 and others added 2 commits May 15, 2026 14:02

Merge branch 'main' into jaap/update_docker

55f13a4

MMathisLab approved these changes May 19, 2026

View reviewed changes

MMathisLab merged commit e7762a6 into main May 19, 2026
54 of 55 checks passed

MMathisLab deleted the jaap/update_docker branch May 19, 2026 08:57

deruyter92 changed the title ~~[Docker 1] Simplify and modernize Dockerfile~~ [Docker] Simplify and modernize Dockerfile May 20, 2026

deruyter92 added the DLC3.0🔥 label May 20, 2026

This was referenced May 21, 2026

Add 3.0 changelog #3340

Merged

Update docker documentation #3344

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Docker] Simplify and modernize Dockerfile#3290

[Docker] Simplify and modernize Dockerfile#3290
MMathisLab merged 13 commits into
mainfrom
jaap/update_docker

deruyter92 commented Apr 21, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

C-Achard left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

deruyter92 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MMathisLab left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

deruyter92 commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

C-Achard left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

deruyter92 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MMathisLab left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

deruyter92 commented Apr 21, 2026 •

edited

Loading