docker-run is a CLI tool for simplified interaction with Docker images. Use it to easily start and attach to Docker containers with useful predefined arguments.

While docker-run can be used with any Docker image, we recommend to also check out our other tools for Docker and ROS.

• docker-ros automatically builds minimal container images of ROS applications
• docker-ros-ml-images provides machine learning-enabled ROS Docker images

The following quickly launches the GUI application xeyes to demonstrate how docker-run takes care of X11 forwarding from container to host. The --verbose flag prints the underlying docker run command that is run under the hood.

docker-run --verbose 607qwq/xeyes

docker-run is designed to be used the same way as the official docker run and docker exec commands.

In general, you can pass the same arguments to docker-run as you would pass to docker run, e.g.

docker-run --volume $(pwd):/volume ubuntu ls /volume

In addition to the arguments you are passing, docker-run however also enables the following features by default. Most of these default features can be disabled, see Usage.

• container removal after exit (--rm)
• interactive tty (--interactive --tty)
• current directory name as container name (--name)
• relative bind mounts (--volume [./RELATIVE_PATH>]:[TARGET_PATH])
• GPU support (--gpus all / --runtime nvidia)
• X11 GUI forwarding

If a container with matching name is already running, docker-run will execute a command in that container via docker exec instead. This lets you quickly attach to a running container without passing any command, e.g.

docker-run --name my-running-container

Unlike with docker run, you can also set the Docker image via the --image arguments, see Usage. This may be required for more complex use cases.

pip install docker-run-cli

# (optional) shell auto-completion
source $(activate-python-docker-run-shell-completion 2> /dev/null)

Warning
Outside of a virtual environment, pip may default to a user-site installation of executables to ~/.local/bin, which may not be present in your shell's PATH. If running docker-run errors with docker-run: command not found, add the directory to your path. (More information)

echo "export PATH=\$HOME/.local/bin:\$PATH" >> ~/.bashrc
source ~/.bashrc

usage: docker-run [--help] [--image IMAGE] [--mwd] [--name NAME] [--no-gpu]
                  [--no-it] [--no-loc] [--no-name] [--no-rm] [--no-tz]
                  [--no-x11] [--verbose] [--version]

Executes `docker run` with the following features enabled by default, each of
which can be disabled individually: container removal after exit, interactive
tty, current directory name as container name, GPU support, X11 GUI
forwarding. Passes any additional arguments to `docker run`. Executes `docker
exec` instead if a container with the specified name (`--name`) is already
running.

optional arguments:
  --help         show this help message and exit
  --image IMAGE  image name (may also be specified without --image as last
                 argument before command)
  --mwd          mount current directory at same path
  --name NAME    container name; generates `docker exec` command if already
                 running
  --no-gpu       disable automatic GPU support
  --no-it        disable automatic interactive tty
  --no-loc       disable automatic locale
  --no-name      disable automatic container name (current directory)
  --no-rm        disable automatic container removal
  --no-tz        disable automatic timezone
  --no-x11       disable automatic X11 GUI forwarding
  --verbose      print generated command
  --version      show program's version number and exit

docker-run can be extended through plugins. Plugins are installed as optional dependencies.

# install specific plugin <PLUGIN_NAME>
pip install docker-run-cli[<PLUGIN_NAME>]

# install all plugins
pip install docker-run-cli[plugins]