Client

Creating a client

To communicate with the Docker daemon, you first need to instantiate a client. The easiest way to do that is by calling the function from_env(). It can also be configured manually by instantiating a DockerClient class.

from_env()

Return a client configured from environment variables.

The environment variables used are the same as those used by the Docker command-line client. They are:

DOCKER_HOST

The URL to the Docker host.

DOCKER_TLS_VERIFY

Verify the host against a CA certificate.

DOCKER_CERT_PATH

A path to a directory containing TLS certificates to use when connecting to the Docker host.

Parameters:
  • version (str) – The version of the API to use. Set to auto to automatically detect the server’s version. Default: auto
  • timeout (int) – Default timeout for API calls, in seconds.
  • max_pool_size (int) – The maximum number of connections to save in the pool.
  • ssl_version (int) – A valid SSL version.
  • assert_hostname (bool) – Verify the hostname of the server.
  • environment (dict) – The environment to read environment variables from. Default: the value of os.environ
  • credstore_env (dict) – Override environment variables when calling the credential store process.
  • use_ssh_client (bool) – If set to True, an ssh connection is made via shelling out to the ssh client. Ensure the ssh client is installed and configured on the host.

Example

>>> import docker
>>> client = docker.from_env()

Client reference

class DockerClient

A client for communicating with a Docker server.

Example

>>> import docker
>>> client = docker.DockerClient(base_url='unix://var/run/docker.sock')
Parameters:
  • base_url (str) – URL to the Docker server. For example, unix:///var/run/docker.sock or tcp://127.0.0.1:1234.
  • version (str) – The version of the API to use. Set to auto to automatically detect the server’s version. Default: 1.35
  • timeout (int) – Default timeout for API calls, in seconds.
  • tls (bool or TLSConfig) – Enable TLS. Pass True to enable it with default options, or pass a TLSConfig object to use custom configuration.
  • user_agent (str) – Set a custom user agent for requests to the server.
  • credstore_env (dict) – Override environment variables when calling the credential store process.
  • use_ssh_client (bool) – If set to True, an ssh connection is made via shelling out to the ssh client. Ensure the ssh client is installed and configured on the host.
  • max_pool_size (int) – The maximum number of connections to save in the pool.
configs

An object for managing configs on the server. See the configs documentation for full details.

containers

An object for managing containers on the server. See the containers documentation for full details.

images

An object for managing images on the server. See the images documentation for full details.

networks

An object for managing networks on the server. See the networks documentation for full details.

nodes

An object for managing nodes on the server. See the nodes documentation for full details.

plugins

An object for managing plugins on the server. See the plugins documentation for full details.

secrets

An object for managing secrets on the server. See the secrets documentation for full details.

services

An object for managing services on the server. See the services documentation for full details.

swarm

An object for managing a swarm on the server. See the swarm documentation for full details.

volumes

An object for managing volumes on the server. See the volumes documentation for full details.

close()

Closes all adapters and as such the session

df()

Get data usage information.

Returns:A dictionary representing different resource categories and their respective data usage.
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.
events()

Get real-time events from the server. Similar to the docker events command.

Parameters:
  • since (UTC datetime or int) – Get events from this point
  • until (UTC datetime or int) – Get events until this point
  • filters (dict) – Filter the events by event time, container or image
  • decode (bool) – If set to true, stream will be decoded into dicts on the fly. False by default.
Returns:

A docker.types.daemon.CancellableStream generator
Raises:

docker.errors.APIError – If the server returns an error.

Example

>>> for event in client.events(decode=True)
...   print(event)
{u'from': u'image/with:tag',
 u'id': u'container-id',
 u'status': u'start',
 u'time': 1423339459}
...

or

>>> events = client.events()
>>> for event in events:
...   print(event)
>>> # and cancel from another thread
>>> events.close()
info()

Display system-wide information. Identical to the docker info command.

Returns:The info as a dict
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.
login()

Authenticate with a registry. Similar to the docker login command.

Parameters:
  • username (str) – The registry username
  • password (str) – The plaintext password
  • email (str) – The email for the registry account
  • registry (str) – URL to the registry. E.g. https://index.docker.io/v1/
  • reauth (bool) – Whether or not to refresh existing authentication on the Docker server.
  • dockercfg_path (str) – Use a custom path for the Docker config file (default $HOME/.docker/config.json if present, otherwise $HOME/.dockercfg)
Returns:

The response from the login request
Return type:

(dict)
Raises:

docker.errors.APIError – If the server returns an error.
ping()

Checks the server is responsive. An exception will be raised if it isn’t responding.

Returns:(bool) The response from the server.
Raises:docker.errors.APIError – If the server returns an error.
version()

Returns version information from the server. Similar to the docker version command.

Returns:The server version information
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.