bake

docker.buildx.bake(
    targets=[],
    builder=None,
    files=[],
    load=False,
    cache=True,
    print=False,
    progress="auto",
    pull=False,
    push=False,
    set={},
    variables={},
    stream_logs=False,
)

Bake is similar to make, it allows you to build things declared in a file.

For example it allows you to build multiple docker image in parallel.

The CLI docs is here and it contains a lot more information.

Arguments

  • targets Union[str, List[str]]: Targets or groups of targets to build.
  • builder Optional[Union[str, python_on_whales.Builder]]: The builder to use.
  • files Union[str, pathlib.Path, List[Union[str, pathlib.Path]]]: Build definition file(s)
  • load bool: Shorthand for set=["*.output=type=docker"]
  • cache bool: Whether to use the cache or not.
  • print bool: Do nothing, just returns the config.
  • progress Union[str, bool]: Set type of progress output ("auto", "plain", "tty", or False). Use plain to keep the container output on screen
  • pull bool: Always try to pull the newer version of the image
  • push bool: Shorthand for set=["*.output=type=registry"]
  • set Dict[str, str]: A list of overrides in the form "targetpattern.key=value".
  • variables Dict[str, str]: A dict containing the values of the variables defined in the hcl file. See https://github.com/docker/buildx#hcl-variables-and-functions

Returns

The configuration used for the bake (files merged + override with the arguments used in the function). It's the loaded json you would obtain by running docker buildx bake --print --load my_target if your command was docker buildx bake --load my_target. Some example here.

from python_on_whales import docker

# returns the config used and runs the builds
config = docker.buildx.bake(["my_target1", "my_target2"], load=True)
assert config == {
    "target": {
        "my_target1": {
            "context": "./",
            "dockerfile": "Dockerfile",
            "tags": ["pretty_image1:1.0.0"],
            "target": "out1",
            "output": ["type=docker"]
        },
        "my_target2": {
            "context": "./",
            "dockerfile": "Dockerfile",
            "tags": ["pretty_image2:1.0.0"],
            "target": "out2",
            "output": ["type=docker"]
        }
    }
}

# returns the config only, doesn't run the builds
config = docker.buildx.bake(["my_target1", "my_target2"], load=True, print=True)

build

docker.buildx.build(
    context_path,
    add_hosts={},
    allow=[],
    build_args={},
    builder=None,
    cache=True,
    cache_from=None,
    cache_to=None,
    file=None,
    labels={},
    load=False,
    network=None,
    output={},
    platforms=None,
    progress="auto",
    pull=False,
    push=False,
    secrets=[],
    ssh=None,
    tags=[],
    target=None,
    stream_logs=False,
)

Build a Docker image with builkit as backend.

Alias: docker.build(...)

A python_on_whales.Image is returned, even when using multiple tags. That is because it will produce a single image with multiple tags. If no image is loaded into the Docker daemon (if push=True for ex), then None is returned.

Arguments

  • context_path Union[str, pathlib.Path]: The path of the build context.
  • add_hosts Dict[str, str]: Hosts to add. add_hosts={"my_host1": "192.168.32.35"}
  • allow List[str]: List of extra privileges. Eg allow=["network.host", "security.insecure"]
  • build_args Dict[str, str]: The build arguments. ex build_args={"PY_VERSION": "3.7.8", "UBUNTU_VERSION": "20.04"}.
  • builder Optional[Union[str, python_on_whales.Builder]]: Specify which builder to use.
  • cache bool: Whether or not to use the cache
  • cache_from Optional[Union[str, Dict[str, str], List[Dict[str, str]]]]: Works only with the container driver. Loads the cache (if needed) from a registry cache_from="user/app:cache" or a directory on the client cache_from="type=local,src=path/to/dir". It's also possible to use a dict or list of dict form for this argument. e.g. cache_from=dict(type="local", src="path/to/dir")
  • cache_to Optional[Union[str, Dict[str, str]]]: Works only with the container driver. Sends the resulting docker cache either to a registry cache_to="user/app:cache", or to a local directory cache_to="type=local,dest=path/to/dir". It's also possible to use a dict form for this argument. e.g. cache_to=dict(type="local", dest="path/to/dir", mode="max")
  • file Optional[Union[str, pathlib.Path]]: The path of the Dockerfile
  • labels Dict[str, str]: Dict of labels to add to the image. labels={"very-secure": "1", "needs-gpu": "0"} for example.
  • load bool: Shortcut for output=dict(type="docker") If True, docker.buildx.build will return a python_on_whales.Image.
  • network Optional[str]: which network to use when building the Docker image
  • output Dict[str, str]: Output destination (format: output={"type": "local", "dest": "path"} Possible output types are ["local", "tar", "oci", "docker", "image", "registry"]. See this link for more details about each exporter.
  • platforms Optional[List[str]]: List of target platforms when building the image. Ex: platforms=["linux/amd64", "linux/arm64"]
  • progress Union[str, bool]: Set type of progress output (auto, plain, tty, or False). Use plain to keep the container output on screen
  • pull bool: Always attempt to pull a newer version of the image
  • push bool: Shorthand for output=dict(type="registry").
  • secrets Union[str, List[str]]: One or more secrets passed as string(s). For example secrets="id=aws,src=/home/my_user/.aws/credentials"
  • ssh Optional[str]: SSH agent socket or keys to expose to the build (format is default|<id>[=<socket>|<key>[,<key>]] as a string)
  • tags Union[str, List[str]]: Tag or tags to put on the resulting image.
  • target Optional[str]: Set the target build stage to build.
  • stream_logs bool: If True this function will return an iterator of strings. You can then read the logs as they arrive.

Returns

A python_on_whales.Image if a Docker image is loaded in the daemon after the build (the default behavior when calling docker.build(...)). Otherwise, None.

create

docker.buildx.create(
    context_or_endpoint=None,
    buildkitd_flags=None,
    config=None,
    driver=None,
    driver_options={},
    name=None,
    use=False,
)

Create a new builder instance

Arguments

  • context_or_endpoint Optional[str]:
  • buildkitd_flags Optional[str]: Flags for buildkitd daemon
  • config Optional[Union[str, pathlib.Path]]: BuildKit config file
  • driver Optional[str]: Driver to use (available: [kubernetes docker docker-container])
  • driver_options Dict[str, str]: Options for the driver. e.g driver_options=dict(network="host")
  • name Optional[str]: Builder instance name
  • use bool: Set the current builder instance to this builder

Returns

A python_on_whales.Builder object.

disk_usage

docker.buildx.disk_usage()

Not yet implemented

inspect

docker.buildx.inspect(x=None)

Returns a builder instance from the name.

Arguments

  • x Optional[str]: If None (the default), returns the current builder. If a string is provided, the builder that has this name is returned.

Returns

A python_on_whales.Builder object.

is_installed

docker.buildx.is_installed()

Returns True if docker buildx is installed and working.

If it's not installed, head to the installation page and follow the instructions.

list

docker.buildx.list()

Returns the list of python_on_whales.Builder available.

prune

docker.buildx.prune(all=False, filters={})

Remove build cache on the current builder.

Arguments

  • all bool: Remove all cache, not just dangling layers
  • filters Dict[str, str]: Filters to use, for example filters=dict(until="24h")

remove

docker.buildx.remove(builder)

Remove a builder

Arguments

  • builder Union[python_on_whales.Builder, str]: The builder to remove

stop

docker.buildx.stop(builder)

Stop the builder instance

Arguments:

builder: The builder to stop. If None (the default value), the current builder is stopped.

use

docker.buildx.use(builder, default=False, global_=False)

Set the current builder instance

Arguments

  • builder Union[python_on_whales.Builder, str]: The builder to use
  • default bool: Set builder as default for the current context
  • __global___ bool: Builder will be used even when changing contexts

version

docker.buildx.version()

Returns the docker buildx version as a string.

from python_on_whales import docker

version = docker.buildx.version()
print(version)
# "github.com/docker/buildx v0.4.2 fb7b670b764764dc4716df3eba07ffdae4cc47b2"

inspect

docker.buildx.imagetools.inspect(name)

Returns the manifest of a Docker image in a registry without pulling it

Notes about the transition between the legacy builder and buildx

Users are encouraged to use buildx in Python-on-whales through the docker.build() function.

Buildx is the next gen Docker builder and a transition is underway to make the docker build shell command use buildx. Python-on-whales has had an opinionated answer on the matter as docker.build() will always use buildx. This is because Python-on-whales was created during the transition and doesn't have an existing user codebase to support.

The legacy builder is still available by calling docker.legacy_build(), but note that

  • It won't work if you use Docker 22.06 or above
  • It won't work if you used docker.buildx.install() or docker buildx install previously
  • It won't work if you had set the environment variable DOCKER_BUILDKIT to 1

Some resources on the matter: