Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Enhancements over upstream

These are additions to the pinned upstream Dev Containers CLI. Standard dev container behavior, including Features, Docker Compose, and lifecycle commands, is described in the usage guide.

Native distribution

The CLI ships as a Rust binary, so standalone, Homebrew, and Python package installations do not require Node.js. Python wheels embed the executable; the Python package does not expose a Python API. The npm packages are an alternative wrapper around the same native executable.

Persistent runtime defaults

Set environment variables once instead of repeating flags. Explicit CLI flags take precedence; unset or blank variables keep the normal defaults.

For Podman:

export DEVCONTAINER_DOCKER_PATH=podman
export DEVCONTAINER_DOCKER_COMPOSE_PATH=podman-compose
devcontainer up --workspace-folder .

Engine paths are executable names or paths, not shell commands with arguments. For example, use podman-compose, not "podman compose".

Environment variableEquivalent flag
DEVCONTAINER_CONFIG--config
DEVCONTAINER_DOCKER_PATH--docker-path
DEVCONTAINER_DOCKER_COMPOSE_PATH--docker-compose-path
DEVCONTAINER_BUILDKIT--buildkit
DEVCONTAINER_USER_DATA_FOLDER--user-data-folder
DEVCONTAINER_CONTAINER_DATA_FOLDER--container-data-folder
DEVCONTAINER_DOTFILES_REPOSITORY--dotfiles-repository
DEVCONTAINER_DOTFILES_INSTALL_COMMAND--dotfiles-install-command
DEVCONTAINER_DOTFILES_TARGET_PATH--dotfiles-target-path
DEVCONTAINER_GPU_AVAILABILITY--gpu-availability
DEVCONTAINER_UPDATE_REMOTE_USER_UID_DEFAULT--update-remote-user-uid-default
DEVCONTAINER_MOUNT_WORKSPACE_GIT_ROOT--mount-workspace-git-root
DEVCONTAINER_MOUNT_GIT_WORKTREE_COMMON_DIR--mount-git-worktree-common-dir
DEVCONTAINER_WORKSPACE_MOUNT_CONSISTENCY--workspace-mount-consistency

DEVCONTAINER_CONFIG resolves relative paths from --workspace-folder, or from the current directory when no workspace is supplied. Use the same value for up and exec to select the same configuration.

Refresh images before starting

devcontainer up --workspace-folder . --pull-always

--pull-always refreshes remote source images and build bases. Compose projects refresh the remote images needed by the selected services and their dependencies. Existing containers can still be reused; add --remove-existing-container when you also want to replace the container.

Additional command options

The native CLI also adds these options to individual commands:

CommandAddition
build--build-no-cache as an alternative to --no-cache
set-up--workspace-folder and --docker-compose-path
exec--secrets-file for environment variables from a JSON file
features test--docker-path to select the container engine
features publish, templates publish--output-dir for a local OCI layout
templates metadata--workspace-folder to resolve local OCI layouts

Collection publishing currently writes local OCI layouts; it does not upload them to a remote registry. See the CLI reference for option syntax.