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.

Parameters:

Name	Type	Description	Default
services	Union[List[str], str, None]	The services to build (as list of strings). If None (default), all services are built. An empty list means that nothing will be built.	None
build_args	Dict[str, str]	Set build-time variables for services. For example build_args={"PY_VERSION": "3.7.8", "UBUNTU_VERSION": "20.04"}.	{}
cache	bool	Set to False if you don't want to use the cache to build your images	True
progress	Optional[str]	Set type of progress output (auto, tty, plain, quiet) (default "auto")	None
pull	bool	Set to True to always attempt to pull a newer version of the image (in the FROM statements for example).	False
quiet	bool	Don't print anything	False
ssh	Optional[str]	Set SSH authentications used when building service images. (use 'default' for using your default SSH Agent)	None
stream_logs	bool	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.	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"

Parameters:

Name	Type	Description	Default
return_json	bool	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.	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.

Parameters:

Name	Type	Description	Default
services	Union[str, List[str], None]	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.	None
build	bool	Build images before starting containers.	False
force_recreate	bool	Recreate containers even if their configuration and image haven't changed.	False
no_build	bool	Don't build an image, even if it's missing.	False
no_recreate	bool	If containers already exist, don't recreate them. Incompatible with force_recreate=True.	False
stream_logs	bool	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.	False

down

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

Stops and removes the containers

Parameters:

Name	Type	Description	Default
remove_orphans	bool	Remove containers for services not defined in the Compose file.	False
remove_images	Optional[str]	Remove images used by services. "local" remove only images that don't have a custom tag. Possible values are "local" and "all".	None
timeout	Optional[int]	Specify a shutdown timeout in seconds (default 10).	None
volumes	bool	Remove named volumes declared in the volumes section of the Compose file and anonymous volumes attached to containers.	False
quiet	bool	If False, send to stderr and stdout the progress spinners with the messages. If True, do not display anything.	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.

Parameters:

Name	Type	Description	Default
service	str	The name of the service.	required
command	List[str]	The command to execute.	required
detach	bool	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.	False
envs	Dict[str, str]	A dictionary of environment variables to set in the container.	{}
index	int	The index of the container to execute the command in (default 1) if there are multiple containers for this service.	1
tty	bool	If True, allocate a pseudo-TTY. Use False to get the output of the command.	True
privileged	bool	If True, run the command in privileged mode.	False
user	Optional[str]	The username to use inside the container.	None
workdir	Union[str, Path, None]	The working directory inside the container.	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

Parameters:

Name	Type	Description	Default
services	Union[str, List[str]]	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.	None
signal	Optional[Union[int, str]]	the signal to send to the container. Default is "SIGKILL"	None

logs

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

View output from containers

Parameters:

Name	Type	Description	Default
services	Union[str, List[str]]	One or more service(s) to view	[]
tail	Optional[str]	Number of lines to show from the end of the logs for each container. (default "all")	None
follow	bool	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.	False
no_log_prefix	bool	Don't print prefix in logs	False
timestamps	bool	Show timestamps	False
since	Optional[str]	Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)	None
until	Optional[str]	Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)	None
stream	bool	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.	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

Parameters:

Name	Type	Description	Default
all	bool	Results include all stopped compose projects.	False
filters	Dict[str, str]	Filter results based on conditions provided.	{}

Returns

A `List[python_on_whales.ComposeProject]`

pause

pause(services=None)

Pause one or more services

Parameters:

Name	Type	Description	Default
services	Union[str, List[str], None]	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.	None

port

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

Returns the public port for a port binding.

Parameters:

Name	Type	Description	Default
service	str	The name of the service.	required
private_port	Union[str, int]	The private port.	required
index	int	Index of the container if service has multiple replicas (default 1)	1
protocol	str	tcp or udp (default "tcp").	'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

Parameters:

Name	Type	Description	Default
services	Union[List[str], str, None]	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.	None
ignore_pull_failures	bool	Pull what it can and ignores images with pull failures	False
include_deps	bool	Also pull services declared as dependencies	False
quiet	bool	By default, the progress bars are printed in stdout and stderr (both). To disable all output, use quiet=True	False
stream_logs	bool	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.	False

push

push(services=None)

Push service images

Parameters:

Name	Type	Description	Default
services	Optional[List[str]]	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.	None

restart

restart(services=None, timeout=None)

Restart containers

Parameters:

Name	Type	Description	Default
services	Union[str, List[str], None]	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.	None
timeout	Union[int, timedelta, None]	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.	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.

Parameters:

Name	Type	Description	Default
services	Union[str, List[str], None]	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.	None
stop	bool	Stop the containers, if required, before removing	False
volumes	bool	Remove any anonymous volumes attached to containers	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.

Parameters:

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

Returns:

Type	Description
Union[str, python_on_whales.components.container.cli_wrapper.Container, Iterable[Tuple[str, bytes]]]	Optional[str]

start

start(services=None, stream_logs=False)

Start the specified services.

Parameters:

Name	Type	Description	Default
services	Union[str, List[str], None]	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.	None
stream_logs	bool	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.	False

stop

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

Stop services

Parameters:

Name	Type	Description	Default
services	Union[str, List[str], None]	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.	None
timeout	Union[int, timedelta, None]	Number of seconds or timedelta (will be converted to seconds). Specify a shutdown timeout. Default is 10s.	None
stream_logs	bool	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.	False

top

top()

Not yet implemented

unpause

unpause(services=None)

Unpause one or more services

Parameters:

Name	Type	Description	Default
services	Union[str, List[str], None]	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.	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)

Start the containers.

Reading the logs of the containers is not yet implemented.

Parameters:

Name	Type	Description	Default
services	Union[List[str], str, None]	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.	None
build	bool	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.	False
detach	bool	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.	False
abort_on_container_exit	bool	If True stops all containers if any container was stopped. Incompatible with detach=True.	False
scales	Dict[str, int]	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}.	{}
attach_dependencies	bool	Attach to dependent containers.	False
force_recreate	bool	Recreate containers even if their configuration and image haven't changed.	False
recreate	bool	Recreate the containers if already exist. recreate=False and force_recreate=True are incompatible.	True
no_build	bool	Don't build an image, even if it's missing.	False
remove_orphans	bool	Remove containers for services not defined in the Compose file.	False
renew_anon_volumes	bool	Recreate anonymous volumes instead of retrieving data from the previous containers.	False
color	bool	If False, it will produce monochrome output.	True
log_prefix	bool	If False, will not display the prefix in the logs.	True
start	bool	Start the service after creating them.	True
quiet	bool	By default, some progress bars and logs are sent to stderr and stdout. Set quiet=True to avoid having any output.	False
wait	bool	Wait for services to be running|healthy. Implies detached mode.	False
no_attach_services	Union[List[str], str, None]	The services not to attach to.	None
pull	Literal['always', 'missing', 'never', None]	Pull image before running (“always”|”missing”|”never”).	None
stream_logs	bool	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.	False

version

version()

Returns the version of docker compose as a str.