docker compose - Python on whales

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.container.ps()]

docker.container.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.

build

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

Build services declared in a yaml compose file.

Arguments

services Optional[List[str]]: The services to build (as list of strings). If None (default), all services are built. An empty list means that nothing will be built.
build_arguments: 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
progress Optional[str]: Set type of progress output (auto, tty, plain, quiet) (default "auto")
pull bool: Set to True to always attempt to pull a newer version of the image (in the FROM statements for example).
quiet bool: Don't print anything
ssh Optional[str]: Set SSH authentications used when building service images. (use 'default' for using your default SSH Agent)

config

docker.compose.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"

Arguments

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.

Returns

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

create

docker.compose.create(services=None, build=False, force_recreate=False, no_build=False, no_recreate=False)

Creates containers for a service.

Arguments

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

down

docker.compose.down(remove_orphans=False, remove_images=None, timeout=None, volumes=False)

Stops and removes the containers

Arguments

remove_orphans bool: Remove containers for services not defined in the Compose file.
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".
timeout Optional[int]: Specify a shutdown timeout in seconds (default 10).
volumes bool: Remove named volumes declared in the volumes section of the Compose file and anonymous volumes attached to containers.

events

docker.compose.events()

Not yet implemented

execute

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

Execute a command in a running container.

Arguments

service str: The name of the service.
command List[str]: The command to execute.
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.
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.
tty bool: If True, allocate a pseudo-TTY. Use False to get the output of the command.
privileged bool: If True, run the command in privileged mode.
user Optional[str]: The username to use inside the container.
workdir Optional[Union[str, pathlib.Path]]: The working directory inside the container.

is_installed

docker.compose.is_installed()

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

kill

docker.compose.kill(services=None, signal=None)

Kills the container(s) of a service

Arguments

services Optional[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.
signal Optional[str]: the signal to send to the container. Default is "SIGKILL"

logs

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

View output from containers

Arguments

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")
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.
no_log_prefix: Don't print prefix in logs
timestamps bool: Show timestamps
since Optional[str]: Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)
until Optional[str]: Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)
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.

Returns

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

pause

docker.compose.pause(services=None)

Pause one or more services

Arguments

services Optional[Union[str, List[str]]]: 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.

port

docker.compose.port()

Not yet implemented

ps

docker.compose.ps()

Returns the containers that were created by the current project.

Returns

A List[python_on_whales.Container]

pull

docker.compose.pull(services=None, ignore_pull_failures=False, include_deps=False, quiet=False)

Pull service images

Arguments

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

push

docker.compose.push(services=None)

Push service images

Arguments

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.

restart

docker.compose.restart(services=None, timeout=None)

Restart containers

Arguments

services Optional[Union[str, List[str]]]: 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.
timeout Optional[Union[int, datetime.timedelta]]: 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.

rm

docker.compose.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.

Arguments

services Optional[Union[str, List[str]]]: 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.
stop bool: Stop the containers, if required, before removing
volumes bool: Remove any anonymous volumes attached to containers

run

docker.compose.run(
    service,
    command=[],
    detach=False,
    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.

Arguments

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

Returns:

Optional[str]

start

docker.compose.start(services=None)

Start the specified services.

Arguments

services Optional[Union[str, List[str]]]: 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.

stop

docker.compose.stop(services=None, timeout=None)

Stop services

Arguments

services Optional[Union[str, List[str]]]: 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.
timeout Optional[Union[int, datetime.timedelta]]: Number of seconds or timedelta (will be converted to seconds). Specify a shutdown timeout. Default is 10s.

top

docker.compose.top()

Not yet implemented

unpause

docker.compose.unpause(services=None)

Unpause one or more services

Arguments

services Optional[Union[str, List[str]]]: 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.

up

docker.compose.up(
    services=None,
    build=False,
    detach=False,
    abort_on_container_exit=False,
    scales={},
    attach_dependencies=False,
    force_recreate=False,
    no_build=False,
    color=True,
    log_prefix=True,
    start=True,
    quiet=False,
)

Start the containers.

Reading the logs of the containers is not yet implemented.

Arguments

services Optional[Union[str, List[str]]]: 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.
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.
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.
abort_on_container_exit bool: If True stops all containers if any container was stopped. Incompatible with detach=True.
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.
force_recreate bool: Recreate containers even if their configuration and image haven't changed.
no_build bool: Don't build an image, even if it's missing.
color bool: If False, it will produce monochrome output.
log_prefix bool: If False, will not display the prefix in the logs.
start bool: Start the service after creating them.
quiet bool: By default, some progress bars and logs are sent to stderr and stdout. Set quiet=True to avoid having any output.

Returns

None at the moment. The plan is to be able to capture and stream the logs later. It's not yet implemented.

version

docker.compose.version()

Returns the version of docker compose as a str.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

Some notes about the compose functions

About docker.compose.images().

build

config

create

down

events

execute

is_installed

kill

logs

pause

port

ps

pull

push

restart

rm

run

start

stop

top

unpause

up

version

About `docker.compose.images()`.