Change Log



  • Added dockerfile param support to (mirrors docker build -f behavior)
  • Added the ability to specify 'auto' as version in Client.__init__, allowing the constructor to autodetect the daemon's API version.


  • Fixed a bug where decoding a result stream using the decode parameter would break when using Python 3.x
  • Fixed a bug where some files in .dockerignore weren't being handled properly
  • Fixed resolve_authconfig issues by bringing it closer to Docker Engine's behavior. This should fix all issues encountered with private registry auth
  • Fixed an issue where passwords containing a colon weren't being handled properly.
  • Bumped requests version requirement, which should fix most of the SSL issues encountered recently.


  • Several integration test improvements.
  • Fixed some unclosed resources in unit tests.
  • Several docs improvements.



  • Added new Client.rename method (docker rename)
  • Added now Client.stats method (docker stats)
  • Added read_only param support to utils.create_host_config and Client.start (docker run --read-only)
  • Added pid_mode param support to utils.create_host_config and Client.start (docker run --pid='host')
  • Added since, until and filters params to
  • Added decode parameter to Client.stats and to decode JSON objects on the fly (False by default).


  • Fixed a bug that caused to crash when the provided source was a remote source.


  • Default API version has been bumped to 1.17 (Docker Engine 1.5.0)
  • Client.timeout is now a public attribute, and users are encouraged to use it when request timeouts need to be changed at runtime.
  • Added Client.api_version as a read-only property.
  • The memswap_limit argument in Client.create_container now accepts string type values similar to mem_limit ('6g', '120000k', etc.)
  • Improved documentation



  • Added support for mac_address in Client.create_container


  • Fixed a bug where streaming responses (pull, push, logs, etc.) were unreliable (#300)
  • Fixed a bug where resolve_authconfig wouldn't properly resolve configuration for private repositories (#468)
  • Fixed a bug where some errors wouldn't be properly constructed in, leading to unhelpful exceptions bubbling up (#466)
  • Fixed a bug where would try to close context when externally provided (custom_context == True) (#458)
  • Fixed an issue in create_host_config where empty sequences wouldn't be interpreted properly (#462)


  • Added resolve_authconfig tests.



  • now indicates a maximum version of requests to work around the boot2docker / assert_hostname bug.
  • Removed invalid exception when using the Registry Hub's FQDN when pulling.
  • Fixed an issue where early HTTP errors weren't handled properly in streaming responses.
  • Fixed a bug where sockets would close unexpectedly using Python 3.x
  • Various fixes for integration tests.


  • Small doc fixes


Breaking changes

  • Passing dns or volumes_from in Client.start with API version < 1.10 will now raise an exception (previously only triggered a warning)


  • Added support for host_config in Client.create_container
  • Added utility method docker.utils.create_host_config to help build a proper HostConfig dictionary.
  • Added support for the pull parameter in
  • Added support for the forcerm parameter in
  • Added support for extra_hosts in Client.start
  • Added support for a custom timeout in Client.wait
  • Added support for custom .dockercfg loading in Client.login (dockercfg_path argument)


  • Fixed a bug where some output wouldn't be streamed properly in streaming chunked responses
  • Fixed a bug where the devices param didn't recognize the proper delimiter
  • Client.login now properly expands the registry URL if provided.
  • Fixed a bug where unicode characters in passed for environment in create_container would break.


  • Several unit tests and integration tests improvements.
  • Client constructor now enforces passing the version parameter as a string.
  • Build context files are now ordered by filename when creating the archive (for consistency with docker mainline behavior)


  • This version introduces breaking changes!

Breaking changes

  • The default SSL protocol is now the highest TLS v1.x (was SSL v2.3 before) (Poodle fix)
  • The history command now returns a dict instead of a raw JSON string.


  • Added the execute command.
  • Added pause and unpause commands.
  • Added support fo the cpuset param in create_container
  • Added support for host devices (devices param in start)
  • Added support for the tail param in logs.
  • Added support for the filters param in images and containers
  • The kwargs_from_env method is now available in the docker.utils module. This should make it easier for boot2docker user to connect to their daemon.


  • Fixed a bug where empty directories weren't correctly included when providing a context to
  • Fixed a bug where UNIX socket connections weren't properly cleaned up, causing ResourceWarnings to appear in some cases.
  • Fixed a bug where docker-py would crash if the docker daemon was stopped while reading a streaming response
  • Fixed a bug with streaming responses in Python 3
  • remove_image now supports a dict containing an Id key as its id parameter (similar to other methods requiring a resource ID)


  • Added new MkDocs documentation. Currently hosted on ReadTheDocs


  • Added tests to sdist
  • Added a Makefile for running tests in Docker
  • Updated Dockerfile


  • Fixed attaching when connecting to the daemon over a UNIX socket.


  • Fixed a bug where sockets were closed immediately when attaching over TLS.


  • Added a assert_hostname option to TLSConfig which can be used to disable verification of hostnames.
  • Fixed SSL not working due to an incorrect version comparison
  • Fixed streams not working on Windows


  • This version introduces breaking changes!
  • Added insecure_registry parameter in Client.push and Client.pull. It defaults to False and code pushing to non-HTTPS private registries might break as a result.
  • Added support for adding and dropping capabilities
  • Added support for restart policy
  • Added support for string values in Client.create_container's mem_limit
  • Added support for .dockerignore file in


  • Fixed timeout behavior in Client.stop


  • Client.create_container provides better validation of the volumes parameter
  • Improved integration tests


  • This version introduces breaking changes!
  • The base_url parameter in the Client constructor should now allow most of the DOCKER_HOST environment values (except for the fd:// protocol)
    • As a result, URLs that don't specify a port are now invalid (similar to the official client's behavior)
  • Added TLS support (see documentation)


  • Fixed an issue with streamed logs in Python 3


  • Added unit tests coverage
  • Various integration tests fixes


  • Default API version is now 1.12 (support for docker 1.0)
  • Added new methods Client.get_image and Client.load_image (docker save and docker load)
  • Added new method
  • Added new method Client.resize
  • can now be provided with a custom context using the custom_context parameter.
  • Added support for memswap_limit parameter in create_container
  • Added support for force parameter in remove_container
  • Added support for force and noprune parameters in remove_image
  • Added support for timestamps parameter in logs
  • Added support for dns_search parameter in start
  • Added support for network_mode parameter in start
  • Added support for size parameter in containers
  • Added support for volumes_from and dns parameters in start. As of API version >= 1.10, these parameters no longer belong to create_container
  • Client.logs now uses the logs endpoint when API version is sufficient


  • Fixed a bug in pull where the repo:tag notation wasn't interpreted properly
  • Fixed a bug in streaming methods with python 3 (unicode, bytes/str related)
  • Fixed a bug in Client.start where legacy notation for volumes wasn't supported anymore.


  • The client now raises DockerExceptions when appropriate. You can import DockerException (and its subclasses) from the docker.errors module to catch them if needed.
  • docker.APIError has been moved to the new docker.errors module as well.
  • Client.insert is deprecated in API version > 1.11
  • Improved integration tests should now run much faster.
  • There is now a single source of truth for the docker-py version number.


  • Default API version is now 1.9
  • Streaming responses no longer yield blank lines.
  • Client.create_container now supports the domainname parameter.
  • volumes_from parameter in Client.create_container now supports iterables.
  • Auth credentials are provided to the docker daemon when using (new feature in API version 1.9)


  • Various fixes for response streams (logs, pull, etc.).
  • Fixed a bug with Client.push when using API version < 1.5
  • Fixed a bug with API version checks.


  • mock has been removed from the runtime requirements.
  • Added installation instructions in the README.


  • This version introduces breaking changes!
  • Support for API version 1.7 through 1.9 (Docker 0.8.0+)
  • Default API version is now 1.8
  • The client has been updated to support Requests 2.x. requests==2.2.1 is now the recommended version.
  • Links can now be specified as tuples in Client.start (see docs for more information)
  • Added support for various options in Client.create_container (network_disabled, cpu_shares, working_dir and entrypoint)
  • Client.attach has been reworked to work similarly to Client.logs minus the historical data.
  • Logs can now be streamed using the stream parameter.
  • Added support for tcp:// URLs as client base_url.
  • Various auth improvements.
  • Added support for custom timeout.


  • Fixed a bug where determining the protocol of a private registry would sometimes yield the wrong result.
  • Fixed a bug where Client.copy wouldn't accept a dict as argument.
  • Fixed several streaming bugs.
  • Removed unused parameter in Client.import_image.
  • The client's base_url now tolerates trailing slashes.


  • Updated integration tests
  • Small doc fixes


  • Support for API version 1.6
  • Added support for links
  • Added support for global request timeout
  • Added signal parameter in Client.kill
  • Added support for publish_all_ports in Client.start
  • Client.pull, Client.push and can be streamed now
  • Added support for websockets in Client.attach
  • Fixed ports for Docker 0.6.5+
  • Added method (access to the /events endpoint)
  • Changed the way the ports and volumes are provided in Client.start and Client.create_container̀€ to make them simpler and more intuitive.


  • Fixed a bug where private registries on HTTPS weren't handled properly
  • Fixed a bug where auth would break with Python 3


  • Test improvements
  • Slight doc improvements


  • Added support for the rm parameter in
  • Added support for tarball imports in Client.import_image through data parameter.
  • The command parameter in Client.create_container is now optional (for containers that include a default run command)


  • Fixed Python 3 support
  • Fixed a bug where anonymous push/pull would break when no authconfig is present
  • Fixed a bug where the quiet parameter wouldn't be taken into account in Client.containers
  • Fixed a bug where Client.push would break when pushing to private registries.
  • Removed unused registry parameter in Client.pull.
  • Removed obsolete custom error message in Client.create_container.


  • docker-py is now unit-tested, and Travis-CI has been enabled on the source repository.


  • Improvements to the tox.ini file


  • Fixed a bug where the package would fail with an ImportError if requests was installed using apt-get
  • Fixed a bug where would fail if given a path parameter.
  • Fixed several bugs in Client.login. It should now work with API versions 1.4, 1.5.
  • Please note that Client.login currently doesn't write auth to the .dockercfg file, thus auth is not persistent when using this method.


  • This version introduces breaking changes!
  • Client.kill, Client.remove_container, Client.remove_image, Client.restart, Client.start, Client.stop and Client.wait don't support varargs anymore.
  • Added commands and Client.copy
  • Added lxc_conf parameter to Client.start
  • Added support for authentication in Client.pull (API version >=1.5)
  • Added support for privileged containers.
  • Error management overhaul. The new version should be more consistent and
  • All methods that expected a container ID as argument now also support a dict containing an Id key.
  • Added license header to python files.
  • Several updates.


  • Fixed several bugs with auth config parsing.
  • Fixed a bug in Client.push where it would raise an exception if the auth config wasn't loaded.
  • Fixed a bug in Client.pull where private registry images wouldn't be parsed properly if it contained port information.


  • now uses tempfiles to store build context instead of storing it in memory
  • Added nocache option to
  • Client.remove_container now raises an exception when trying to remove a running container
  • Client.create_container now accepts dicts for the environment parameter


  • Fixed a bug in Client.create_container on Python 2.6 where unicode commands would fail to be parsed
  • Fixed a bug in where the tag parameter would not be taken into account


  • Added support for API connection through UNIX socket (default for docker 0.5.2+)


  • The client now tries to load the auth config from ~/.dockercfg. This is necessary to use the push command if API version is >1.0


  • Added a quiet parameter to (mirrors the q parameter in the API)


  • Fixed a bug where the build command would list tar contents before sending the request
  • Fixed a bug in Client.port


  • This version introduces breaking changes!
  • Switched to server side build system
  • Removed the BuilderClient
  • Added support for contextual builds
  • Added support for remote URL builds
  • Added python 3 support
  • Added bind mounts support
  • Added API version support
  • Fixed a bug where Client.port would fail if provided with a port of type number
  • Fixed a bug where Client._post_json wouldn't set the Content-Type header to application/json


  • Added support for custom loggers in
  • Added Client.attach command
  • Added support for ADD command in builder
  • Fixed a bug in Client.logs
  • Improved unit tests


  • Added tag support for the builder
  • Use shlex to parse plain string commands when creating a container
  • Fixed several bugs in the builder
  • Fixed the quiet option in Client.images
  • Unit tests


  • Improved error reporting


  • Fixed a bug in Client.tag
  • Fixed a bug where generated images would be removed after a successful build


  • Implemented first version of the builder client