docker buildx

BuildxCLI

bake

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

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.

PARAMETER	DESCRIPTION
`targets`	Targets or groups of targets to build. TYPE: `Union[str, List[str]]` DEFAULT: `[]`
`builder`	The builder to use. TYPE: `Optional[ValidBuilder]` DEFAULT: `None`
`files`	Build definition file(s) TYPE: `Union[ValidPath, List[ValidPath]]` DEFAULT: `[]`
`load`	Shorthand for `set=[".output=type=docker"]` TYPE:* `bool` DEFAULT: `False`
`cache`	Whether to use the cache or not. TYPE: `bool` DEFAULT: `True`
`print`	Do nothing, just returns the config. TYPE: `bool` DEFAULT: `False`
`progress`	Set type of progress output (`"auto"`, `"plain"`, `"tty"`, or `False`). Use plain to keep the container output on screen TYPE: `Literal['auto', 'plain', 'tty', False]` DEFAULT: `'auto'`
`pull`	Always try to pull the newer version of the image TYPE: `bool` DEFAULT: `False`
`push`	Shorthand for `set=[".output=type=registry"]` TYPE:* `bool` DEFAULT: `False`
`set`	A list of overrides in the form `"targetpattern.key=value"`. TYPE: `Dict[str, str]` DEFAULT: `{}`
`variables`	A dict containing the values of the variables defined in the hcl file. See https://github.com/docker/buildx#hcl-variables-and-functions TYPE: `Dict[str, str]` DEFAULT: `{}`
`remote_definition`	Remote context in which to find bake files TYPE: `Union[str, None]` DEFAULT: `None`

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

build(context_path, add_hosts={}, allow=[], attest=None, build_args={}, build_contexts={}, builder=None, cache=True, cache_from=None, cache_to=None, file=None, labels={}, load=False, metadata_file=None, network=None, output={}, platforms=None, progress='auto', provenance=None, pull=False, push=False, sbom=None, 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.

PARAMETER	DESCRIPTION
`context_path`	The path of the build context. TYPE: `ValidPath`
`add_hosts`	Hosts to add. `add_hosts={"my_host1": "192.168.32.35"}` TYPE: `Dict[str, str]` DEFAULT: `{}`
`allow`	List of extra privileges. Eg `allow=["network.host", "security.insecure"]` TYPE: `List[str]` DEFAULT: `[]`
`attest`	Attestation parameters. Eg `attest={"type": "sbom", "generator": "my_image"}` TYPE: `Optional[Dict[str, str]]` DEFAULT: `None`
`build_args`	The build arguments. ex `build_args={"PY_VERSION": "3.7.8", "UBUNTU_VERSION": "20.04"}`. TYPE: `Dict[str, str]` DEFAULT: `{}`
`build_contexts`	Additional build contexts. `build_contexts={[name]: [value], ...}` Supports local directories, git repositories, HTTP URL to a tarball, a docker image defined with a `docker-image://` prefix, and the `oci-layout://` protocol. ex `build_contexts={"project2": "../path/to/project2/src", "qumu-src": "https://github.com/qemu/qemu.git"}`. TYPE: `Dict[str, Union[str, ValidPath]]` DEFAULT: `{}`
`builder`	Specify which builder to use. TYPE: `Optional[ValidBuilder]` DEFAULT: `None`
`cache`	Whether or not to use the cache TYPE: `bool` DEFAULT: `True`
`cache_from`	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")` TYPE: `Union[str, Dict[str, str], List[Dict[str, str]], None]` DEFAULT: `None`
`cache_to`	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")` TYPE: `Union[str, Dict[str, str], None]` DEFAULT: `None`
`file`	The path of the Dockerfile TYPE: `Optional[ValidPath]` DEFAULT: `None`
`labels`	Dict of labels to add to the image. `labels={"very-secure": "1", "needs-gpu": "0"}` for example. TYPE: `Dict[str, str]` DEFAULT: `{}`
`load`	Shortcut for `output=dict(type="docker")` If `True`, `docker.buildx.build` will return a `python_on_whales.Image`. TYPE: `bool` DEFAULT: `False`
`network`	which network to use when building the Docker image TYPE: `Optional[str]` DEFAULT: `None`
`output`	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. TYPE: `Dict[str, str]` DEFAULT: `{}`
`platforms`	List of target platforms when building the image. Ex: `platforms=["linux/amd64", "linux/arm64"]` TYPE: `Optional[List[str]]` DEFAULT: `None`
`progress`	Set type of progress output (auto, plain, tty, or False). Use plain to keep the container output on screen TYPE: `Literal['auto', 'plain', 'tty', False]` DEFAULT: `'auto'`
`provenance`	Shortand for `attest={"type": "provenance"}`. Eg `provenance=True` or `provenance=dict(mode="max")`. `provenance=False` might be needed if you are having the issue Default image output from buildx v0.10 cannot run on Google Cloud Run or AWS Lambda TYPE: `Union[bool, Dict[str, str], None]` DEFAULT: `None`
`pull`	Always attempt to pull a newer version of the image TYPE: `bool` DEFAULT: `False`
`push`	Shorthand for `output=dict(type="registry")`. TYPE: `bool` DEFAULT: `False`
`sbom`	Shorthand for `attest={"type": "sbom"}`. Eg `sbom=True`. TYPE: `Union[bool, Dict[str, str], None]` DEFAULT: `None`
`secrets`	One or more secrets passed as string(s). For example `secrets="id=aws,src=/home/my_user/.aws/credentials"` TYPE: `Union[str, List[str]]` DEFAULT: `[]`
`ssh`	SSH agent socket or keys to expose to the build (format is `default\|<id>[=<socket>\|<key>[,<key>]]` as a string) TYPE: `Optional[str]` DEFAULT: `None`
`tags`	Tag or tags to put on the resulting image. TYPE: `Union[str, List[str]]` DEFAULT: `[]`
`target`	Set the target build stage to build. TYPE: `Optional[str]` DEFAULT: `None`
`stream_logs`	If `True` this function will return an iterator of strings. You can then read the logs as they arrive. TYPE: `bool` DEFAULT: `False`
`metadata_file`	Path where build metadata should be written. Equivalent to the CLI flag `--metadata-file` and only used when provided. TYPE: `Optional[ValidPath]` DEFAULT: `None`

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

create(context_or_endpoint=None, bootstrap=False, buildkitd_flags=None, config=None, platforms=None, driver=None, driver_options={}, name=None, use=False, append=False)

Create a new builder instance

PARAMETER	DESCRIPTION
`context_or_endpoint`	TYPE: `Optional[str]` DEFAULT: `None`
`bootstrap`	Boot builder after creation TYPE: `bool` DEFAULT: `False`
`buildkitd_flags`	Flags for buildkitd daemon TYPE: `Optional[str]` DEFAULT: `None`
`config`	BuildKit config file TYPE: `Optional[ValidPath]` DEFAULT: `None`
`platforms`	Comma-separated list of platforms of the form OS/architecture/variant. Ex: `platforms=["linux/amd64", "linux/arm64"]` TYPE: `Optional[List[str]]` DEFAULT: `None`
`driver`	Driver to use (available: [kubernetes docker docker-container]) TYPE: `Optional[str]` DEFAULT: `None`
`driver_options`	Options for the driver. e.g `driver_options=dict(network="host")` TYPE: `Dict[str, str]` DEFAULT: `{}`
`name`	Builder instance name TYPE: `Optional[str]` DEFAULT: `None`
`use`	Set the current builder instance to this builder TYPE: `bool` DEFAULT: `False`
`append`	Append a node to the current builder instance, in this case `name` must be provided. TYPE: `bool` DEFAULT: `False`

Returns

A `python_on_whales.Builder` object.

disk_usage

disk_usage()

Not yet implemented

inspect

inspect(x=None, bootstrap=False)

Returns a builder instance from the name.

PARAMETER	DESCRIPTION
`x`	If `None` (the default), returns the current builder. If a string is provided, the builder that has this name is returned. TYPE: `Optional[str]` DEFAULT: `None`
`bootstrap`	If set to True, ensure builder has booted before inspecting. TYPE: `bool` DEFAULT: `False`

Returns

A `python_on_whales.Builder` object.

is_installed

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

list()

Returns the list of python_on_whales.Builder available.

prune

prune(all=False, filters={}, stream_logs=False)

Remove build cache on the current builder.

PARAMETER	DESCRIPTION
`all`	Remove all cache, not just dangling layers TYPE: `bool` DEFAULT: `False`
`filters`	Filters to use, for example `filters=dict(until="24h")` TYPE: `Dict[str, str]` DEFAULT: `{}`
`stream_logs`	If `True` this function will return an iterator of strings. You can then read the logs as they arrive. If `False` (the default value), then the function returns `None`, but when it returns, then the prune operation has already been done. TYPE: `bool` DEFAULT: `False`

remove

remove(builder)

Remove a builder

PARAMETER	DESCRIPTION
`builder`	The builder to remove TYPE: `Union[Builder, str]`

stop

stop(builder)

Stop the builder instance

PARAMETER	DESCRIPTION
`builder`	The builder to stop. If `None` (the default value), the current builder is stopped. TYPE: `Optional[ValidBuilder]`

use

use(builder, default=False, global_=False)

Set the current builder instance

PARAMETER	DESCRIPTION
`builder`	The builder to use TYPE: `Union[Builder, str]`
`default`	Set builder as default for the current context TYPE: `bool` DEFAULT: `False`
`global_`	Builder will be used even when changing contexts TYPE: `bool` DEFAULT: `False`

version

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"

ImagetoolsCLI

create

create(sources=[], tags=[], append=False, files=[], dry_run=False, builder=None)

Create a new manifest list based on source manifests. The source manifests can be manifest lists or single platform distribution manifests and must already exist in the registry where the new manifest is created. If only one source is specified, create performs a carbon copy.

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

PARAMETER	DESCRIPTION
`sources`	The sources manifest to create, change TYPE: `List[str]` DEFAULT: `[]`
`append`	Append to existing manifest TYPE: `bool` DEFAULT: `False`
`dry_run`	Show final image instead of pushing TYPE: `bool` DEFAULT: `False`
`files`	Read source descriptor from file TYPE: `List[Union[str, Path]]` DEFAULT: `[]`
`builder`	The builder to use. TYPE: `Optional[str]` DEFAULT: `None`

inspect

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: