BuildxCLI
bake
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.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
targets |
Union[str, List[str]]
|
Targets or groups of targets to build. |
[]
|
builder |
Optional[ValidBuilder]
|
The builder to use. |
None
|
files |
Union[ValidPath, List[ValidPath]]
|
Build definition file(s) |
[]
|
load |
bool
|
Shorthand for |
False
|
cache |
bool
|
Whether to use the cache or not. |
True
|
print |
bool
|
Do nothing, just returns the config. |
False
|
progress |
Literal['auto', 'plain', 'tty', False]
|
Set type of progress output ( |
'auto'
|
pull |
bool
|
Always try to pull the newer version of the image |
False
|
push |
bool
|
Shorthand for |
False
|
set |
Dict[str, str]
|
A list of overrides in the form |
{}
|
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
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, 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.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context_path |
ValidPath
|
The path of the build context. |
required |
add_hosts |
Dict[str, str]
|
Hosts to add. |
{}
|
allow |
List[str]
|
List of extra privileges.
Eg |
[]
|
attest |
Optional[Dict[str, str]]
|
Attestation parameters. Eg |
None
|
build_args |
Dict[str, str]
|
The build arguments.
ex |
{}
|
build_contexts |
Dict[str, Union[str, ValidPath]]
|
Additional build contexts.
|
{}
|
builder |
Optional[ValidBuilder]
|
Specify which builder to use. |
None
|
cache |
bool
|
Whether or not to use the cache |
True
|
cache_from |
Union[str, Dict[str, str], List[Dict[str, str]], None]
|
Works only with the container driver. Loads the cache
(if needed) from a registry |
None
|
cache_to |
Union[str, Dict[str, str], None]
|
Works only with the container driver. Sends the resulting
docker cache either to a registry |
None
|
file |
Optional[ValidPath]
|
The path of the Dockerfile |
None
|
labels |
Dict[str, str]
|
Dict of labels to add to the image.
|
{}
|
load |
bool
|
Shortcut for |
False
|
network |
Optional[str]
|
which network to use when building the Docker image |
None
|
output |
Dict[str, str]
|
Output destination
(format: |
{}
|
platforms |
Optional[List[str]]
|
List of target platforms when building the image. Ex:
|
None
|
progress |
Literal['auto', 'plain', 'tty', False]
|
Set type of progress output (auto, plain, tty, or False). Use plain to keep the container output on screen |
'auto'
|
provenance |
Union[bool, Dict[str, str], None]
|
Shortand for |
None
|
pull |
bool
|
Always attempt to pull a newer version of the image |
False
|
push |
bool
|
Shorthand for |
False
|
sbom |
Union[bool, Dict[str, str], None]
|
Shorthand for |
None
|
secrets |
Union[str, List[str]]
|
One or more secrets passed as string(s). For example
|
[]
|
ssh |
Optional[str]
|
SSH agent socket or keys to expose to the build
(format is |
None
|
tags |
Union[str, List[str]]
|
Tag or tags to put on the resulting image. |
[]
|
target |
Optional[str]
|
Set the target build stage to build. |
None
|
stream_logs |
bool
|
If |
False
|
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, buildkitd_flags=None, config=None, platforms=None, driver=None, driver_options={}, name=None, use=False)
Create a new builder instance
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context_or_endpoint |
Optional[str]
|
|
None
|
buildkitd_flags |
Optional[str]
|
Flags for buildkitd daemon |
None
|
config |
Optional[ValidPath]
|
BuildKit config file |
None
|
platforms |
Optional[List[str]]
|
Comma-separated list of platforms of the form OS/architecture/variant. Ex:
|
None
|
driver |
Optional[str]
|
Driver to use (available: [kubernetes docker docker-container]) |
None
|
driver_options |
Dict[str, str]
|
Options for the driver.
e.g |
{}
|
name |
Optional[str]
|
Builder instance name |
None
|
use |
bool
|
Set the current builder instance to this builder |
False
|
Returns
A `python_on_whales.Builder` object.
disk_usage
disk_usage()
Not yet implemented
inspect
inspect(x=None)
Returns a builder instance from the name.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x |
Optional[str]
|
If |
None
|
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.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
all |
bool
|
Remove all cache, not just dangling layers |
False
|
filters |
Dict[str, str]
|
Filters to use, for example |
{}
|
stream_logs |
bool
|
If |
False
|
remove
remove(builder)
Remove a builder
Parameters:
Name | Type | Description | Default |
---|---|---|---|
builder |
Union[Builder, str]
|
The builder to remove |
required |
stop
stop(builder)
Stop the builder instance
Parameters:
Name | Type | Description | Default |
---|---|---|---|
builder |
Optional[ValidBuilder]
|
The builder to stop. If |
required |
use
use(builder, default=False, global_=False)
Set the current builder instance
Parameters:
Name | Type | Description | Default |
---|---|---|---|
builder |
Union[Builder, str]
|
The builder to use |
required |
default |
bool
|
Set builder as default for the current context |
False
|
global_ |
bool
|
Builder will be used even when changing contexts |
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.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sources |
List[str]
|
The sources manifest to create, change |
[]
|
append |
bool
|
Append to existing manifest |
False
|
dry_run |
bool
|
Show final image instead of pushing |
False
|
files |
List[Union[str, Path]]
|
Read source descriptor from file |
[]
|
builder |
Optional[str]
|
The builder to use. |
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()
ordocker buildx install
previously - It won't work if you had set the environment variable
DOCKER_BUILDKIT
to1
Some resources on the matter: