rocker: injecting your host setup into a published Docker image without rebuilding it

The problem is combinatorial image maintenance

rocker exists because of a specific pain in Docker workflows, and the README explains it well enough to decide whether you have it. Suppose you use an official published image and need NVIDIA support. You can do that with docker-compose or plain docker, but then you have to build and publish the combinatorial images of all possible driver configurations, and you have to manually pass the correct runtime arguments each time. The README pushes this further: when you want to combine several extra features, the number of images scales in a polynomial manner and maintenance becomes unmanageable. rocker inverts that. You invoke the plugins you need, and it uses multi-stage builds to customize the container for your specific case, so you can keep using official upstream images without maintaining a plethora of parallel builds. The upstream project is Open Source Robotics Foundation, the licence is Apache-2.0, and the current release is v0.4.0.

UID matching is the first feature, not an afterthought

The README separates a primary goal from a secondary one, and the primary one is about file permissions. The goal of rocker is to support the use of Docker in cases where containers are affected by the local environment, and the primary example given is setting up file permissions inside the container to match the user outside, so mounted files have the same UID as the host. The point is practical: you can go in and out of different containers while using the same workspace on your host, which is what you want when testing on different platforms. The mechanism is described as dynamically generating overlays on the same core image after detecting the local conditions required. The user extension does the work, creating a user inside the container with the same settings as the host and running commands inside the container as that user. The home extension then mounts the host home directory, and the two together are what make a bind-mounted workspace behave.

The built-in extensions cover the usual local environment differences

Extensions are implemented as entry points, and there are several built in. x11 enables the use of X11 inside the container via the host X instance. nvidia enables NVIDIA graphics cards for rendering and cuda enables NVIDIA CUDA in the container. user creates a user inside the container matching the host and runs commands as that user. home mounts the user's home directory into the container. pulse mounts pulse audio into the container, and ssh passes through ssh access to the container. Beyond the named extensions, the README says you also get access to many of the usual Docker arguments, listing device, env, volume, name, network, ipc, privileged, and the resource limits cpus, memory and shm-size. So the container you end up with is a normal Docker container with a generated overlay, not a special runtime, which means anything you can run with docker you can run with rocker.

The extension point is a Python entry point group

The setup.py makes the extension mechanism concrete. The package registers a rocker.extensions entry point group, and the built-ins are listed there as class paths: cpu_limits points to rocker.constraint_extensions:CpuLimits, cuda to rocker.nvidia_extension:Cuda, detach to rocker.extensions:Detach, devices to rocker.extensions:Devices, dev_helpers to rocker.extensions:DevHelpers, env to rocker.extensions:Environment, expose to rocker.extensions:Expose, and git to rocker.git_extension:Git, with more entries following in the same pattern. Alongside that there are two console scripts, rocker pointing at rocker.cli:main and detect_docker_image_os pointing at rocker.cli:detect_image_os. That second script is worth noting, since detecting the OS of an image is exactly the kind of thing extensions need to branch on. The practical consequence is that installing a third-party extension is a matter of installing a package that declares the entry point, which is why the README lists externally maintained extensions as ordinary GitHub repositories rather than as patches.

The ecosystem around rocker is where most of its value sits

The README separates two kinds of outside contribution. Externally maintained extensions are plugins that add a capability: off-your-rocker, mp_rocker, ghrocker, novnc_rocker, template_rocker, deps_rocker, pixi_rocker, conda_rocker, palanteer_rocker and lazygit_rocker. The pattern is visible in the names. conda_rocker and pixi_rocker cover Python environment provisioning, template_rocker generates templates, deps_rocker installs dependencies, and novnc_rocker brings a browser-based VNC view, which pairs with the built-in x11 extension. The second category is externally maintained wrappers, which the README describes as drop-in replacements for rocker so that all the existing behaviour stays the same. rockerc puts rocker commands into a YAML config file, and rockervsc attaches a VS Code instance to the launched container. If your workflow is repeated multi-line shell invocations, the wrapper is often the thing you actually want.

Installing it, and the NVIDIA and rootless caveats

The README gives Debian packages as the recommended route, with instructions for setting up the ROS repositories first and then installing python3-rocker from apt. Otherwise there is pip, with pip install rocker, and an Arch option through the AUR, where the AUR helpers paru and similar install python-rocker or python-rocker-git. The prerequisites are a recent Docker installation. The NVIDIA option has been tested on specific Ubuntu, kernel and driver combinations listed in a table, from 16.04 with nvidia-384 through 22.04 with nvidia-driver-470, and it needs nvidia-docker 2 installed. For rootless Docker there is a caveat worth reading closely. Since cgroups are not supported in rootless mode, the NVIDIA container runtime config has to be changed, and the README warns that this leads to a Failed to initialize NVML: Unknown Error if Docker is executed as root.

[nvidia-container-cli]
no-cgroups = true

For Intel integrated graphics, the devices flag mounts the device directory into the container.

A small Python package with an old dependency footprint

The setup.py is short and shows what rocker itself is made of. The install requirements are empy, pexpect, packaging and urllib3, plus importlib-metadata only on Python versions below 3.8, with a comment that it can be removed once RHEL 8 and other 3.6 based systems are out of support cycles. The Docker client is added conditionally, with a fallback to the old docker-py name on pre-2.0 installs, detected by reading /etc/os-release for xenial and by checking the installed docker version. Package data includes the templates directory with its em files, which is where the generated overlay Dockerfiles come from. The package layout uses src/ as the package directory, with the package named rocker, and the repository has a test directory, a codecov.yml, a setup.cfg, a stdeb.cfg for Debian packaging, a CHANGELOG.md and a wishlist.txt. The repository is not archived and the last push was on 2026-10-19, the same day as the v0.4.0 release.

Editorial conclusion

rocker fits a robotics or graphics developer who wants to run a published base image with their own uid, their GPU drivers and their home directory mounted, without maintaining a fork of every image they use. It does not fit a deployment pipeline that needs reproducible immutable images, since the overlay is generated at run time on the machine that runs it. Verify first that your host is one of the configurations the README lists for NVIDIA, check the rootless mode cgroups note before editing the NVIDIA runtime config, and keep the list of extensions you actually use pinned in your own scripts, because extension behaviour comes from entry points that third parties can supply.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. osrf/rocker on GitHub
4. README
5. Releases