docker compose

Some notes about the compose functions

Behind the scenes, the Go implementation of Docker compose is called a.k.a. Compose v2, not the Python implementation.

You can verify that docker compose is installed by running

docker compose --help

Be careful! it's different from docker-compose --help! Notice the - between 'docker' and 'compose'. Compose v2 has no - in the command.

If that doesn't work, then install the cli plugin. it's just a single binary to download.

The Go implementation of compose is still experimental, so take the appropriate precautions.

If you don't need to set any project-wide options, like the project name or the compose file path, you can just import docker and start working.

from python_on_whales import docker

docker.compose.build()
docker.compose.up()
...
docker.compose.down()

Otherwise, you have to define your project-wide options only once, when creating the Docker client.

from python_on_whales import DockerClient

docker = DockerClient(compose_files=["./my-compose-file.yml"])

docker.compose.build()
docker.compose.up()
...
docker.compose.down()

You have multiple compose options available (like profiles, env_files, project name) when creating the Docker client. You can check them out in the DockerClient documentation.

About docker.compose.images().

The Docker command line has a docker compose images command. Python-on-whales doesn't have an equivalent because it's trivial to do so with existing functions.

images = [docker.image.inspect(container.image) for container in docker.compose.ps()]

• docker.compose.ps() returns the list of all containers in the compose stack.
• container.image gives you the id of the Docker image of the container as a str.
• docker.image.inspect() gives you a python_on_whales.Image from a str.

ComposeCLI

build

build(services=None, build_args={}, cache=True, progress=None, pull=False, quiet=False, ssh=None, stream_logs=False)

Build services declared in a yaml compose file.

PARAMETER	DESCRIPTION
services	The services to build (as list of strings). If None (default), all services are built. An empty list means that nothing will be built. TYPE: Union[List[str], str, None] DEFAULT: None
build_args	Set build-time variables for services. For example build_args={"PY_VERSION": "3.7.8", "UBUNTU_VERSION": "20.04"}. TYPE: Dict[str, str] DEFAULT: {}
cache	Set to False if you don't want to use the cache to build your images TYPE: bool DEFAULT: True
progress	Set type of progress output (auto, tty, plain, quiet) (default "auto") TYPE: Optional[str] DEFAULT: None
pull	Set to True to always attempt to pull a newer version of the image (in the FROM statements for example). TYPE: bool DEFAULT: False
quiet	Don't print anything TYPE: bool DEFAULT: False
ssh	Set SSH authentications used when building service images. (use 'default' for using your default SSH Agent) TYPE: Optional[str] DEFAULT: None
stream_logs	If False this function returns None. If True, this function returns an Iterable of Tuple[str, bytes] where the first element is the type of log ("stdin" or "stdout"). The second element is the log itself, as bytes, you'll need to call .decode() if you want the logs as str. See the streaming guide if you are not familiar with the streaming of logs in Python-on-whales. TYPE: bool DEFAULT: False

config

config(return_json=False)

Returns the configuration of the compose stack for further inspection.

For example

from python_on_whales import docker
project_config = docker.compose.config()
print(project_config.services["my_first_service"].image)
"redis"

PARAMETER

DESCRIPTION

return_json

If False, a ComposeConfig object will be returned, and you 'll be able to take advantage of your IDE autocompletion. If you want the full json output, you may use return_json. In this case, you'll get lists and dicts corresponding to the json response, unmodified. It may be useful if you just want to print the config or want to access a field that was not in the ComposeConfig class. TYPE: bool DEFAULT: False

Returns

A `ComposeConfig` object if `return_json` is `False`, and a `dict` otherwise.

create

create(services=None, build=False, force_recreate=False, no_build=False, no_recreate=False, stream_logs=False)

Creates containers for a service.

PARAMETER	DESCRIPTION
services	The name of the services for which the containers will be created. The default None means that the containers for all services will be created. A single string means we will create the container for a single service. A list of string means we will create the containers for each service in the list. An empty list means nothing will be created, the function call is then a no-op. TYPE: Union[str, List[str], None] DEFAULT: None
build	Build images before starting containers. TYPE: bool DEFAULT: False
force_recreate	Recreate containers even if their configuration and image haven't changed. TYPE: bool DEFAULT: False
no_build	Don't build an image, even if it's missing. TYPE: bool DEFAULT: False
no_recreate	If containers already exist, don't recreate them. Incompatible with force_recreate=True. TYPE: bool DEFAULT: False
stream_logs	If False this function returns None. If True, this function returns an Iterable of Tuple[str, bytes] where the first element is the type of log ("stdin" or "stdout"). The second element is the log itself, as bytes, you'll need to call .decode() if you want the logs as str. See the streaming guide if you are not familiar with the streaming of logs in Python-on-whales. TYPE: bool DEFAULT: False

down

down(services=None, remove_orphans=False, remove_images=None, timeout=None, volumes=False, quiet=False, stream_logs=False)

Stops and removes the containers

PARAMETER	DESCRIPTION
services	The services to stop. If None (default), all services are stopped. If an empty list is provided, the function call does nothing, it's a no-op. TYPE: Union[List[str], str, None] DEFAULT: None
remove_orphans	Remove containers for services not defined in the Compose file. TYPE: bool DEFAULT: False
remove_images	Remove images used by services. "local" remove only images that don't have a custom tag. Possible values are "local" and "all". TYPE: Optional[str] DEFAULT: None
timeout	Specify a shutdown timeout in seconds (default 10). TYPE: Optional[int] DEFAULT: None
volumes	Remove named volumes declared in the volumes section of the Compose file and anonymous volumes attached to containers. TYPE: bool DEFAULT: False
quiet	If False, send to stderr and stdout the progress spinners with the messages. If True, do not display anything. TYPE: bool DEFAULT: False

execute

execute(service, command, detach=False, envs={}, index=1, tty=True, privileged=False, user=None, workdir=None)

Execute a command in a running container.

PARAMETER	DESCRIPTION
service	The name of the service. TYPE: str
command	The command to execute. TYPE: List[str]
detach	If True, detach from the container after the command exits. In this case, nothing is returned by the function. By default, the execute command returns only when the command has finished running, and the function will raise an exception DockerException if the command exits with a non-zero exit code. If False, the command is executed and the stdout is returned. TYPE: bool DEFAULT: False
envs	A dictionary of environment variables to set in the container. TYPE: Dict[str, str] DEFAULT: {}
index	The index of the container to execute the command in (default 1) if there are multiple containers for this service. TYPE: int DEFAULT: 1
tty	If True, allocate a pseudo-TTY. Use False to get the output of the command. TYPE: bool DEFAULT: True
privileged	If True, run the command in privileged mode. TYPE: bool DEFAULT: False
user	The username to use inside the container. TYPE: Optional[str] DEFAULT: None
workdir	The working directory inside the container. TYPE: Union[str, Path, None] DEFAULT: None

is_installed

is_installed()

Returns True if docker compose (the one written in Go) is installed and working.

kill

kill(services=None, signal=None)

Kills the container(s) of a service

PARAMETER	DESCRIPTION
services	One or more service(s) to kill. The default (None) is to kill all services. A string means the call will kill one single service. A list of service names can be provided to kill multiple services in one function call. An empty list means that no services are going to be killed, the function is then a no-op. TYPE: Union[str, List[str]] DEFAULT: None
signal	the signal to send to the container. Default is "SIGKILL" TYPE: Optional[Union[int, str]] DEFAULT: None

logs

logs(services=[], tail=None, follow=False, no_log_prefix=False, timestamps=False, since=None, until=None, stream=False)

View output from containers

PARAMETER	DESCRIPTION
services	One or more service(s) to view TYPE: Union[str, List[str]] DEFAULT: []
tail	Number of lines to show from the end of the logs for each container. (default "all") TYPE: Optional[str] DEFAULT: None
follow	Follow log output WARNING: With this option, docker.compose.logs() will not return at all. Use it exclusively with stream=True. You can loop on the logs but the loop will never end. TYPE: bool DEFAULT: False
no_log_prefix	Don't print prefix in logs TYPE: bool DEFAULT: False
timestamps	Show timestamps TYPE: bool DEFAULT: False
since	Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) TYPE: Optional[str] DEFAULT: None
until	Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) TYPE: Optional[str] DEFAULT: None
stream	Similar to the stream argument of docker.run(). This function will then return and iterator that will yield a tuple (source, content) with source being "stderr" or "stdout". content is the content of the line as bytes. Take a look at the user guide to have an example of the output. TYPE: bool DEFAULT: False

Returns

`str` if `stream=False` (the default), `Iterable[Tuple[str, bytes]]`
if `stream=True`.

ls

ls(all=False, filters={})

Returns a list of docker compose projects

PARAMETER	DESCRIPTION
all	Results include all stopped compose projects. TYPE: bool DEFAULT: False
filters	Filter results based on conditions provided. TYPE: Dict[str, str] DEFAULT: {}

Returns

A `List[python_on_whales.ComposeProject]`

pause

pause(services=None)

Pause one or more services

PARAMETER	DESCRIPTION
services	None (the default) means pause all containers of all compose services. A string means that the call will pause the container of a specific service. A list of string means the call will pause the containers of all the services specified. So if an empty list is provided, then this function call is a no-op. TYPE: Union[str, List[str], None] DEFAULT: None

port

port(service, private_port, index=1, protocol='tcp')

Returns the public port for a port binding.

PARAMETER	DESCRIPTION
service	The name of the service. TYPE: str
private_port	The private port. TYPE: Union[str, int]
index	Index of the container if service has multiple replicas (default 1) TYPE: int DEFAULT: 1
protocol	tcp or udp (default "tcp"). TYPE: str DEFAULT: 'tcp'

Returns

tuple with (host, port). If port is unknown, then host and port are None.

ps

ps(services=None, all=False)

Returns the containers that were created by the current project.

Returns

A `List[python_on_whales.Container]`

pull

pull(services=None, ignore_pull_failures=False, include_deps=False, quiet=False, stream_logs=False)

Pull service images

PARAMETER	DESCRIPTION
services	The list of services to select. Only the images of those services will be pulled. If no services are specified (None) (the default behavior) all images of all services are pulled. If an empty list is provided, then the function call is a no-op. TYPE: Union[List[str], str, None] DEFAULT: None
ignore_pull_failures	Pull what it can and ignores images with pull failures TYPE: bool DEFAULT: False
include_deps	Also pull services declared as dependencies TYPE: bool DEFAULT: False
quiet	By default, the progress bars are printed in stdout and stderr (both). To disable all output, use quiet=True TYPE: bool DEFAULT: False
stream_logs	If False this function returns None. If True, this function returns an Iterable of Tuple[str, bytes] where the first element is the type of log ("stdin" or "stdout"). The second element is the log itself, as bytes, you'll need to call .decode() if you want the logs as str. See the streaming guide if you are not familiar with the streaming of logs in Python-on-whales. TYPE: bool DEFAULT: False

push

push(services=None)

Push service images

PARAMETER	DESCRIPTION
services	The list of services to select. Only the images of those services will be pushed. If no services are specified (None, the default behavior) all images of all services are pushed. If an empty list is provided, then the function call is a no-op. TYPE: Optional[List[str]] DEFAULT: None

restart

restart(services=None, timeout=None)

Restart containers

PARAMETER	DESCRIPTION
services	The names of one or more services to restart (str or list of str). If the argument is not specified, services is None and all services are restarted. If services is an empty list, then the function call is a no-op. TYPE: Union[str, List[str], None] DEFAULT: None
timeout	The shutdown timeout (int are interpreted as seconds). None means the CLI default value (10s). See the docker stop docs for more details about this argument. TYPE: Union[int, timedelta, None] DEFAULT: None

rm

rm(services=None, stop=False, volumes=False)

Removes stopped service containers

By default, anonymous volumes attached to containers will not be removed. You can override this with volumes=True.

Any data which is not in a volume will be lost.

PARAMETER	DESCRIPTION
services	The names of one or more services to remove (str or list of str). If None (the default) then all services are removed. If an empty list is provided, this function call is a no-op. TYPE: Union[str, List[str], None] DEFAULT: None
stop	Stop the containers, if required, before removing TYPE: bool DEFAULT: False
volumes	Remove any anonymous volumes attached to containers TYPE: bool DEFAULT: False

run

run(service, command=[], build=False, detach=False, labels={}, name=None, tty=True, stream=False, dependencies=True, publish=[], remove=False, service_ports=False, use_aliases=False, user=None, workdir=None)

Run a one-off command on a service.

PARAMETER	DESCRIPTION
service	The name of the service. TYPE: str
command	The command to execute. TYPE: List[str] DEFAULT: []
detach	if True, returns immediately with the Container. If False, returns the command stdout as string. TYPE: bool DEFAULT: False
labels	Add or override labels TYPE: Dict[str, str] DEFAULT: {}
name	Assign a name to the container. TYPE: Optional[str] DEFAULT: None
dependencies	Also start linked services. TYPE: bool DEFAULT: True
publish	Publish a container's port(s) to the host. TYPE: List[ValidPortMapping] DEFAULT: []
service_ports	Enable service's ports and map them to the host. TYPE: bool DEFAULT: False
remove	Automatically remove the container when it exits. TYPE: bool DEFAULT: False
use_aliases	Use the service's network aliases in the connected network(s). TYPE: bool DEFAULT: False
tty	Allocate a pseudo-TTY. Allow the process to access your terminal to write on it. TYPE: bool DEFAULT: True
stream	Similar to docker.run(..., stream=True). TYPE: bool DEFAULT: False
user	Username or UID, format: "<name|uid>[:<group|gid>]" TYPE: Optional[str] DEFAULT: None
workdir	Working directory inside the container TYPE: Union[None, str, Path] DEFAULT: None

RETURNS	DESCRIPTION
Union[str, Container, Iterable[Tuple[str, bytes]]]	Optional[str]

start

start(services=None, stream_logs=False)

Start the specified services.

PARAMETER	DESCRIPTION
services	The names of one or more services to start. If None (the default), it means all services will start. If an empty list is provided, this function call is a no-op. TYPE: Union[str, List[str], None] DEFAULT: None
stream_logs	If False this function returns None. If True, this function returns an Iterable of Tuple[str, bytes] where the first element is the type of log ("stdin" or "stdout"). The second element is the log itself, as bytes, you'll need to call .decode() if you want the logs as str. See the streaming guide if you are not familiar with the streaming of logs in Python-on-whales. TYPE: bool DEFAULT: False

stop

stop(services=None, timeout=None, stream_logs=False)

Stop services

PARAMETER	DESCRIPTION
services	The names of one or more services to stop (str or list of str). If None (the default), it means all services will stop. If an empty list is provided, this function call is a no-op. TYPE: Union[str, List[str], None] DEFAULT: None
timeout	Number of seconds or timedelta (will be converted to seconds). Specify a shutdown timeout. Default is 10s. TYPE: Union[int, timedelta, None] DEFAULT: None
stream_logs	If False this function returns None. If True, this function returns an Iterable of Tuple[str, bytes] where the first element is the type of log ("stdin" or "stdout"). The second element is the log itself, as bytes, you'll need to call .decode() if you want the logs as str. See the streaming guide if you are not familiar with the streaming of logs in Python-on-whales. TYPE: bool DEFAULT: False

top

top()

Not yet implemented

unpause

unpause(services=None)

Unpause one or more services

PARAMETER	DESCRIPTION
services	One or more service to unpause. If None (the default), all services are unpaused. If services is an empty list, the function call does nothing, it's a no-op. TYPE: Union[str, List[str], None] DEFAULT: None

up

up(services=None, build=False, detach=False, abort_on_container_exit=False, scales={}, attach_dependencies=False, force_recreate=False, recreate=True, no_build=False, remove_orphans=False, renew_anon_volumes=False, color=True, log_prefix=True, start=True, quiet=False, wait=False, no_attach_services=None, pull=None, stream_logs=False, wait_timeout=None)

Start the containers.

Reading the logs of the containers is not yet implemented.

PARAMETER	DESCRIPTION
services	The services to start. If None (default), all services are started. If an empty list is provided, the function call does nothing, it's a no-op. TYPE: Union[List[str], str, None] DEFAULT: None
build	If True, build the docker images before starting the containers even if a docker image with this name already exists. If False (the default), build only the docker images that do not already exist. TYPE: bool DEFAULT: False
detach	If True, run the containers in the background. If False this function returns only when all containers have stopped. Incompatible with abort_on_container_exit=True. TYPE: bool DEFAULT: False
abort_on_container_exit	If True stops all containers if any container was stopped. Incompatible with detach=True. TYPE: bool DEFAULT: False
scales	Scale SERVICE to NUM instances. Overrides the scale setting in the Compose file if present. For example: scales={"my_service": 2, "my_other_service": 5}. TYPE: Dict[str, int] DEFAULT: {}
attach_dependencies	Attach to dependent containers. TYPE: bool DEFAULT: False
force_recreate	Recreate containers even if their configuration and image haven't changed. TYPE: bool DEFAULT: False
recreate	Recreate the containers if already exist. recreate=False and force_recreate=True are incompatible. TYPE: bool DEFAULT: True
no_build	Don't build an image, even if it's missing. TYPE: bool DEFAULT: False
remove_orphans	Remove containers for services not defined in the Compose file. TYPE: bool DEFAULT: False
renew_anon_volumes	Recreate anonymous volumes instead of retrieving data from the previous containers. TYPE: bool DEFAULT: False
color	If False, it will produce monochrome output. TYPE: bool DEFAULT: True
log_prefix	If False, will not display the prefix in the logs. TYPE: bool DEFAULT: True
start	Start the service after creating them. TYPE: bool DEFAULT: True
quiet	By default, some progress bars and logs are sent to stderr and stdout. Set quiet=True to avoid having any output. TYPE: bool DEFAULT: False
wait	Wait for services to be running|healthy. Implies detached mode. TYPE: bool DEFAULT: False
no_attach_services	The services not to attach to. TYPE: Union[List[str], str, None] DEFAULT: None
pull	Pull image before running (“always”|”missing”|”never”). TYPE: Literal['always', 'missing', 'never', None] DEFAULT: None
stream_logs	If False this function returns None. If True, this function returns an Iterable of Tuple[str, bytes] where the first element is the type of log ("stdin" or "stdout"). The second element is the log itself, as bytes, you'll need to call .decode() if you want the logs as str. See the streaming guide if you are not familiar with the streaming of logs in Python-on-whales. TYPE: bool DEFAULT: False
wait_timeout	Maximum duration to wait for the project to be running|healthy TYPE: Optional[int] DEFAULT: None

version

version()

Returns the version of docker compose as a str.