NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #220 most downloaded on PyPI
A Python library for the Docker Engine API.
Last release 2 months ago
09 Jul 2026
Ships unpredictably
gaps range from 1 weeks to 2.1 years
Nearly every release is documented
notes for 57 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
10 years old
66 releases · first in 2016
Fixed image loading to avoid depending on the deprecated JSONMessage.error field
docker.from_env() now honors the active Docker CLI context when DOCKER_HOST is not set.
DOCKER_CONTEXT or the current context in ~/.docker/config.json, matching Docker CLI behavior more closely.DOCKER_HOST explicitly, set DOCKER_CONTEXT=default, or pass use_context=False to DockerClient.from_env().docker.from_context() / DockerClient.from_context() for explicitly creating a client from a Docker CLI context.exec_run documentation for the stream parameterJSONMessage.error fieldFull Changelog: 7.1.0...7.2.0
One column per quarter.
Stopped checking for deprecated container and image related fields ( Container and ContainerConfig )
invalid tag format errorsConfigCollection), which failed with a KeyError due to the name fielddocker-py by applying the suggested fixsetup-python github actionContainer and ContainerConfig)NetworkSettings.Networks.<network>.Aliases due to engine changespackaging dependency by @akx in #3205hatchling and hatch-vcs by @akx in #3207container.logs() by @BobDu in #2240Full Changelog: 7.0.0...7.1.0
Removed SSL version ( ssl_version ) and explicit hostname check ( assert_hostname ) options
ssl_version) and explicit hostname check (assert_hostname) options (#3185)
assert_hostname has not been used since Python 3.6 and was removed in 3.12pip install docker[websockets] to include websocket-client dependencydocker-py hijacks the TCP connection and does not use Websocketsattach_socket(container, ws=True)networking_config support for containers.create() (#3121)
network_driver_opt (added in 6.1.0)health() property to container that returns status (e.g. unhealthy) (#3147)pause option to container.commit() (#3159)rshared, private) (#3164)filters, keep_storage, and all in prune_builds() on API v1.39+ (#3192)docker.errors.NotFound on 404 responses (#3156)requirements.txt (used for development/tests) (#3183)Network.connect parameters in client.containers.run and client.containers.create by @Skazza94 in #3121Full Changelog: 6.1.3...7.0.0
Removed SSL version ( ssl_version ) and explicit hostname check ( assert_hostname ) options
assert_hostname has not been used since Python 3.6 and was removed in 3.12
Python 3.7+ supports TLSv1.3 by default
Websocket support is no longer included by default
Use pip install docker[websockets] to include websocket-client dependency
By default, docker-py hijacks the TCP connection and does not use Websockets
Websocket client is only required to use attach_socket(container, ws=True)
Python 3.7 no longer officially supported (reached end-of-life June 2023)
Python 3.12 support
Full networking_config support for containers.create()
Replaces network_driver_opt (added in 6.1.0)
Add health() property to container that returns status (e.g. unhealthy )
Add pause option to container.commit()
Add support for bind mount propagation (e.g. rshared , private )
Add filters , keep_storage , and all parameters to prune_builds() (requires API v1.39+)
Consistently return docker.errors.NotFound on 404 responses
Validate tag format before image push
Upgraded urllib3 version in requirements.txt (used for development/tests)
Documentation typo fixes & formatting improvements
Fixed integration test compatibility for newer Moby engine versions
Switch to ruff for linting
ℹ️ See 7.0.0b2 for full release notes
ℹ️ See 7.0.0b2 for full release notes
ssl_version) and explicit hostname check (assert_hostname) options (#3185)
assert_hostname has not been used since Python 3.6 and was removed in 3.12pip install docker[websockets] to include websocket-client dependencydocker-py hijacks the TCP connection and does not use Websocketsattach_socket(container, ws=True)filters, keep_storage, and all in prune_builds() on API v1.39+ (#3192)Commit Log: 7.0.0b2...7.0.0b3
ℹ️ This is identical to 7.0.0b1 , which was not correctly released due to a CI pipeline issue.
ℹ️ This is identical to 7.0.0b1, which was not correctly released due to a CI pipeline issue.
ssl_version) and explicit hostname check (assert_hostname) options (#3185)
assert_hostname has not been used since Python 3.6 and was removed in 3.12pip install docker[websockets] to include websocket-client dependencydocker-py hijacks the TCP connection and does not use Websocketsattach_socket(container, ws=True)networking_config support for containers.create() (#3121)
network_driver_opt (added in 6.1.0)health() property to container that returns status (e.g. unhealthy) (#3147)pause option to container.commit() (#3159)rshared, private) (#3164)docker.errors.NotFound on 404 responses (#3156)requirements.txt (used for development/tests) (#3183)Network.connect parameters in client.containers.run and client.containers.create by @Skazza94 in #3121Full Changelog: 6.1.3...7.0.0b2
fix: eventlet compatibility by @tito in #3132
Fix for socket timeouts on long docker exec calls
Full Changelog: 6.1.1...6.1.2
Errors are no longer returned during client initialization if the credential helper cannot be found. A warning will be emitted instead, and an error i
containers.stats() hanging with stream=Truecontainers.diff() methoddiff method by @john-b-yang in #3115Full Changelog: 6.1.0...6.1.1
Errors are no longer returned during client initialization if the credential helper cannot be found. A warning will be emitted instead, and an error i
poll() instead of select() on non-Windows platformsnetwork_driver_opt on container run / createone-shot on container statsstatus on services listcontainer.exec_* operationsnetwork_driver_opt to client.containers run and create by @Skazza94 in #3083one-shot to container API stats by @aroxby-wayscript in #3089status parameter to services list API by @lorinbucher in #3093Full Changelog: 6.0.1...6.1.0
This version is not compatible with requests 2.29+ or urllib3 2.x. Either add requests < 2.29 and urllib3 < 2 to your requirements or upgrade to to th
This version is not compatible with requests 2.29+ or urllib3 2.x.
Either add requests < 2.29 and urllib3 < 2 to your requirements or upgrade to to the latest docker-py release.
The pipe has been ended errors on Windows (#3056)since / until) (#3031)Full Changelog: https://github.com/docker/docker-py/compare/6.0.0...6.0.1
Fix for The pipe has been ended errors on Windows
Support floats for container log filtering by timestamp ( since / until )
Fix: fix CVE-2020-28243 by @errorcode7 in https://github.com/docker/docker-py/pull/2910
docker[tls] extra is deprecated and a no-op,
use docker for same functionality (TLS support is always available now)use_ssh_client=False) will now
reject unknown host keys with paramiko.ssh_exception.SSHException__version__platform (e.g. linux/amd64, darwin/arm64) to container create & runGlobalJob and ReplicatedJobs for Swarmremove() method on Imageforce param to disable() on Pluginpywin32.dockerignore filesProxyCommand option for SSH connectionsrequirements.txt to latest versionspackaging instead of distutils for Version by @FrancescoCasalegno in https://github.com/docker/docker-py/pull/2931gzip documentation to BuildApiMixin by @SauravMaheshkar in https://github.com/docker/docker-py/pull/2929preexec_func always by @q0w in https://github.com/docker/docker-py/pull/2920global-job and replicated-job modes in Docker Swarm by @kinday in https://github.com/docker/docker-py/pull/3016Full Changelog: https://github.com/docker/docker-py/compare/5.0.3...6.0.0
remove duplicate 'on' in comment by @thomasgassmann in https://github.com/docker/docker-py/pull/2370
gzip documentation to BuildApiMixin by @SauravMaheshkar in https://github.com/docker/docker-py/pull/2929preexec_func always by @q0w in https://github.com/docker/docker-py/pull/2920global-job and replicated-job modes in Docker Swarm by @kinday in https://github.com/docker/docker-py/pull/3016Full Changelog: https://github.com/docker/docker-py/compare/6.0.0b1...6.0.0b2
Fix: fix CVE-2020-28243 by @errorcode7 in https://github.com/docker/docker-py/pull/2910
packaging instead of distutils for Version by @FrancescoCasalegno in https://github.com/docker/docker-py/pull/2931Full Changelog: https://github.com/docker/docker-py/compare/5.0.3...6.0.0b1
List of PRs / issues for this release
List of PRs / issues for this release
cap_add and cap_drop parameters to service create and ContainerSpectemplating parameter to config createList of PRs / issues for this release
List of PRs / issues for this release
List of PRs / issues for this release
List of PRs / issues for this release
List of PRs / issues for this release
limit parameter to image search endpointKeyError exception on secret create> This is the last release with support for Python 2.7 and 3.5
Warning
This is the last release with support for Python 2.7 and 3.5
List of PRs / issues for this release
LD_LIBRARY_PATH and SSL_CERT_FILE environment variables when shelling out to the ssh clientList of PRs / issues for this release
List of PRs / issues for this release
List of PRs / issues for this release
List of PRs / issues for this release
List of PRs / issues for this release
List of PRs / issues for this release
List of PRs / issues for this release
Avoid setting unsuported parameter for subprocess.Popen on Windows
Replace use of deprecated “filter” argument on “”docker/api/image”
List of PRs / issues for this release
List of PRs / issues for this release
latest on pullList of PRs / issues for this release
List of PRs / issues for this release
autofloatidentityfile optionAdd DeviceRequest type to expose host resources such as GPUs
DeviceRequest type to expose host resources such as GPUsDriverOpts in EndpointConfigList of PRs / issues for this release
Add DeviceRequest type to expose host resources such as GPUs
Add support for DriverOpts in EndpointConfig
Disable compression by default when using container.get_archive method
Update default API version to v1.39
Update test engine version to 19.03.12
List of PRs / issues for this release
List of PRs / issues for this release
List of PRs / issues for this release
tls on Context constructorList of PRs / issues for this release
List of PRs / issues for this release
win32pipe.WaitNamedPipe throw exception in Windows containersHostname, Username, Port and ProxyCommand settings from .ssh/config when on SSHparamiko.WarningPolicy()paramiko to warndocker.ContextAPIList of PRs / issues for this release
List of PRs / issues for this release
INDEX_URL logic in build.py _set_auth_headersNetworkAttachmentConfig for service create/update--platform tests for changes in docker engineList of PRs / issues for this release
List of PRs / issues for this release
HealthCheck is created/configuredList of PRs / issues for this release
List of PRs / issues for this release
credentials subpackage that caused import errors in
Python 3.7List of PRs / issues for this release
List of PRs / issues for this release
APIClient.update_service, APIClient.init_swarm, and
DockerClient.swarm.init now return a dict from the API's response bodyAPIClient.build and DockerClient.images.build, the use_config_proxy
parameter now defaults to Trueinit_path is no longer a valid parameter for HostConfigSCTP ports for port mappingsContainerSpecs now support the init parameterDockerClient.swarm.init and APIClient.init_swarm now support the
data_path_addr parameterAPIClient.update_swarm and DockerClient.swarm.update now support the
rotate_manager_unlock_key parameterAPIClient.update_service returns the API's response body as a dictAPIClient.init_swarm, and DockerClient.swarm.init now return the API's
response body as a dictPlacementPreference instances to produce a valid API typebuildargs in build could cause
the library to attempt accessing attributes of a None valuevolume_driver parameter in
DockerClient.containers.create would result in an errorAPIClient.inspect_distribution now correctly sets the authentication
headers on the request, allowing it to be used with private repositories
This change also applies to DockerClient.get_registry_dataNothing published for this version
List of PRs / issues for this release
List of PRs / issues for this release
parse_host afterwards, letting base_url with the original value.List of PRs / issues for this release
List of PRs / issues for this release
List of PRs / issues for this release
List of PRs / issues for this release
attach and exec_start). Learn
more at https://docker-py.readthedocs.io/en/stable/user_guides/multiplex.htmluse_config_proxy parameter to the following methods:
APIClient.build, APIClient.create_container, DockerClient.images.build
and DockerClient.containers.run (False by default). This parameter
will become True by default in the 4.0.0 release.config.json file.DockerClient.swarm.init now returns a boolean value as advertised.List of PRs / issues for this release
List of PRs / issues for this release
pip install "docker[ssh]"named parameter in Image.save, which may be
used to ensure the resulting tarball retains the image's name on save.\\?\
prefix would fail with some relative Dockerfile paths.DockerClient would fail when
setting the stream parameter to True.requests dependency has been bumped
to 2.20.0Bumped version of pyOpenSSL in requirements.txt and setup.py to prevent installation of a vulnerable version
List of PRs / issues for this release
pyOpenSSL in requirements.txt and setup.py to prevent
installation of a vulnerable versionList of PRs / issues for this release
List of PRs / issues for this release
uts_mode parameter in HostConfigUpdateConfig constructor now allows rollback as a valid
value for failure_actionrollback_config in APIClient.create_service,
APIClient.update_service, DockerClient.services.create and
Service.update.build methodDockerClient.services.createuser value of 0 to be ignored in
APIClient.create_container and DockerClient.containers.createList of PRs / issues for this release
List of PRs / issues for this release
** patterns in
.dockerignore filesList of PRs / issues for this release
List of PRs / issues for this release
APIClient and DockerClient constructors now accept a credstore_env
parameter. When set, values in this dictionary are added to the environment
when executing the credential store process.DockerClient.networks.prune now properly returns the operation's resultplugin_privileges method can now be called for plugins requiring
authentication to accessread_only parameter when creating a service using
the DockerClient was being ignoredService.scale would not properly update the service's
mode, causing the operation to fail silentlyList of PRs / issues for this release
List of PRs / issues for this release
prune_builds in APIClient and DockerClient.imagesignore_removed parameter in
DockerClient.containers.liststop and restart now gets properly adjusted to
allow for the operation to finish in the specified timeList of PRs / issues for this release
List of PRs / issues for this release
ValueError when attempting to
build with a Dockerfile on a different Windows drive.List of PRs / issues for this release
List of PRs / issues for this release
attach(), logs() and events() now have a
cancel() method to let consumers stop the iteration client-side.build() methods can now handle Dockerfiles supplied outside of the
build context.sparse argument to DockerClient.containers.list()isolation parameter to build() methods.close() method to DockerClientAPIClient.inspect_distribution() method and
DockerClient.images.get_registry_data()
RegistryData classList of PRs / issues for this release
List of PRs / issues for this release
List of PRs / issues for this release
List of PRs / issues for this release
./List of PRs / issues for this release
List of PRs / issues for this release
Fixed a bug that led to a Dockerfile not being included in the build context in some situations when the Dockerfile’s path was prefixed with ./
List of PRs / issues for this release
List of PRs / issues for this release
.dockerignore comments to be read as exclusion
patternsList of PRs / issues for this release
List of PRs / issues for this release
device_cgroup_rules in host configgeneric_resources when creating a Resources
object.chunk_size parameter in export,
get_archive and get_image (Image.save)force_update method to the Service class.Service.update, when the force_update parameter is set to True,
the current force_update counter is incremented by one in the update
request.login() was being ignored if the
SDK was configured to use a credential store.DockerClient.images.pull to pull an image by digest
would lead to an exception being raised..dockerignore rules should now be respected as defined by the spec,
including respect for last-line precedence and proper handling of absolute
pathspass credential store is now properly supported.List of PRs / issues for this release
List of PRs / issues for this release
APIClient.login didn't populate the _auth_configs
dictionary properly, causing subsequent pull and push operations to failList of PRs / issues for this release
List of PRs / issues for this release
APIClient.copy has been removed. Users should use APIClient.get_archive
instead.APIClient.insert has been removed. Users may use APIClient.put_archive
combined with APIClient.commit to replicate the method's behavior.utils.ping_registry and utils.ping have been removed.stream in APIClient.buildcpu_shares, cpuset, dns, mem_limit, memswap_limit,
volume_driver, volumes_from in APIClient.create_container. These are
all replaced by their equivalent in create_host_configinsecure_registry in APIClient.login, APIClient.pull,
APIClient.push, DockerClient.images.push and DockerClient.images.pullviz in APIClient.imagesendpoint_config in APIClient.create_service and
APIClient.update_service is now endpoint_specname in DockerClient.images.pull is now repositoryAPIClient.wait and Container.wait now return a dict representing
the API's response instead of returning the status code directly.DockerClient.images.load now returns a list of Image objects that have
for the images that were loaded, instead of a log stream.Container.exec_run now returns a tuple of (exit_code, output) instead of
just the output.DockerClient.images.build now returns a tuple of (image, build_logs)
instead of just the image object.APIClient.export, APIClient.get_archive and APIClient.get_image now
return generators streaming the raw binary data from the server's response.DockerClient.images.pull now returns a list of
Images associated to the pulled repository instead of just the latest
image.scale method to the Service model ; this method is a shorthand
that calls update_service with the required number of replicasplatform parameter in APIClient.build,
DockerClient.images.build, APIClient.pull and DockerClient.images.pulluntil parameter in APIClient.logs and
Container.logsworkdir argument in APIClient.exec_create and
Container.exec_runcondition argument in APIClient.wait and
Container.waitEndpointSpec using
the {published_port: (target_port, protocol, publish_mode)} syntax.isolation parameter in ContainerSpec,
DockerClient.services.create and Service.updateAPIClient.attach_socket, APIClient.exec_create now allow specifying a
detach_keys combination. If unspecified, the value from the config.json
file will be used.dockerignore would break builds
on WindowsDockerClient.containers.runnetworks data provided to create_service and
update_service would be sent incorrectly to the Engine with API < 1.25latest tag using the
DockerClient will no longer raise a NotFound exceptionList of PRs / issues for this release
List of PRs / issues for this release
unlock_swarm and get_unlock_key methods to the APIClient.
unlock and get_unlock_key to DockerClient.swarm.greedy parameter to DockerClient.networks.list, yielding
additional details about the listed networks.cpu_rt_runtime and cpu_rt_period as parameters to
APIClient.create_host_config and DockerClient.containers.run.order argument to UpdateConfig.fetch_current_spec to APIClient.update_service and Service.update
that will retrieve the current configuration of the service and merge it with
the provided parameters to determine the new configuration.build method tried to include inaccessible files
in the context, leading to obscure errors during the build phase
(inaccessible files inside the context now raise an IOError instead).build method would try to read from FIFOs present
inside the build context, causing it to hang.APIClient.stop will no longer override the stop_timeout value present
in the container's configuration.DockerClient.containers.run would crash if the
auto_remove parameter was set to True.listen_addr in join_swarm to match the
one in init_swarm.APIError object.List of PRs / issues for this release
List of PRs / issues for this release
attach and
exec_run methods.List of PRs / issues for this release
List of PRs / issues for this release
mounts in APIClient.create_host_config and
DockerClient.containers.runconsistency, tmpfs_size and tmpfs_mode when
creating mount objects.Mount objects now support the tmpfs and npipe types.extra_hosts in the build methods.APIClient: create_config, inspect_config, remove_config,
configsDockerClient: configs.create, configs.get, configs.list and
the Config model.configs parameter to ContainerSpec. Each item in the configs
list must be a docker.types.ConfigReference instance.ContainerSpec
object: groups, open_stdin, read_only, stop_signal, helathcheck,
hosts, ns_config, configs, privileges.docker.types:
ConfigReference, DNSConfig, Privileges, SwarmExternalCA.driver in APIClient.create_secret and
DockerClient.secrets.create.scope in APIClient.inspect_network and
APIClient.create_network, and their DockerClient equivalent.create_swarm_spec:
external_cas, labels, signing_ca_cert, signing_ca_key,
ca_force_rotate, autolock_managers, log_driver. These additions
also apply to DockerClient.swarm.init.insert_defaults in APIClient.inspect_service and
DockerClient.services.get.id member on Swarm objects wasn't being populated.attach, exec_run) to disappear.List of PRs / issues for this release
List of PRs / issues for this release
** in .dockerignore would
raise an exceptionattach with the stream argument set to False
would raise an exceptionList of PRs / issues for this release
List of PRs / issues for this release
squash parameter in APIClient.build and
DockerClient.images.build.load_image will now return a
generator of progress as JSON dicts.remove_image now returns the content of the API's response.auto_remove parameter in
DockerClient.containers.run was not taken into account..dockerignore patterns starting with a slash
were ignored.** patterns in .dockerignoreFROM a private Docker Hub image when not
using a cred store would fail.create_service or update_service with
task_template as a dict would raise an exception.attach and exec_run.DockerClient.containers.run will no longer attempt to stream logs if the
log driver doesn't support the operation.docker[tls] notation.List of issues / PRs for this release
List of issues / PRs for this release
split_port utility would raise an exception when
passed a non-string argument.Nothing published for this version
List of PRs / issues for this release
List of PRs / issues for this release
target and network_mode parameters in
APIClient.build and DockerClient.images.build.runtime parameter in APIClient.create_container
and DockerClient.containers.run.ingress parameter in APIClient.create_network and
DockerClient.networks.create.placement configuration in docker.types.TaskTemplate.tty configuration in docker.types.ContainerSpec.start_period configuration in docker.types.Healthcheck.credHelpers section in Docker's configuration file is now recognized.DockerClient using docker.from_env
wouldn't correctly set the default timeout value.DockerClient.secrets was not accessible as a property.DockerClient.build would sometimes return the wrong
image.HostConfig.nano_cpus exceeding 2^32 would
raise a type error.Image.tag now properly returns True when the operation is successful.APIClient.logs and Container.logs now raise an exception if the since
argument uses an unsupported type instead of ignoring the value.NullResource exception when
the resource ID was provided using a keyword argument.APIClient instances can now be pickled.List of PRs / issues for this release
List of PRs / issues for this release
HostConfig parameters: volume_driver,
cpu_count, cpu_percent, nano_cpus, cpuset_mems.verbose parameter in APIClient.inspect_network and
DockerClient.networks.get.environment parameter in APIClient.exec_create
and Container.exec_runreload_config method to APIClient, that lets the user reload
the config.json data from disk.labels property to the Image and Container classes.image property to the Container class.replicas to zero in ServiceMode would not
register as a valid entry.DockerClient.images.build would report a failure after
a successful build if a tag was set.DockerClient.images.pull would fail to return the
corresponding image object if a tag was set.mounts provided to APIClient.create_service
would sometimes be parsed incorrectly.Network.containers would crash when no containers
were associated with the network.Network.connect and Network.disconnect would not
accept some of the documented parameters.cpuset_cpus parameter would not be properly set in
APIClient.create_host_config.networks argument in DockerClient.containers.run has been
replaced with a (working) singular network argument.List of PRs / issues for this release
List of PRs / issues for this release
status_code attribute of APIError exceptions would
not reflect the expected value.events method would time out unexpectedly if no
data was sent by the engine for a given amount of time.Your coding agent can read these notes before it upgrades. Set up the MCP server →