Client

class aiodocker.docker.Docker(url: str | None = None, connector: BaseConnector | None = None, session: ClientSession | None = None, timeout: ClientTimeout | None = None, ssl_context: SSLContext | None = None, api_version: str = 'auto', context: str | None = None)[source]

The Docker client as the main entrypoint to the sub-APIs such as container, images, networks, swarm and services, etc. You may access such sub-API collections via the attributes of the client instance, like:

docker = aiodocker.Docker()
await docker.containers.list()
await docker.images.pull(...)

Docker Host Resolution Precedence

The Docker host is determined using the following precedence order (highest to lowest):

  1. url parameter - Explicitly provided Docker daemon address

  2. context parameter - Explicitly specified Docker context name

  3. DOCKER_HOST environment variable - Falls back when no explicit context specified

  4. DOCKER_CONTEXT environment variable - Specifies which Docker context to use

  5. currentContext from ~/.docker/config.json - Default context set by docker CLI

  6. Socket auto-detection - Searches common socket paths (e.g., /var/run/docker.sock)

Note: Explicit constructor parameters (url, context) take precedence over environment variables (DOCKER_HOST, DOCKER_CONTEXT). This follows the principle that explicit code configuration overrides implicit environment configuration, matching the pattern used in the official Docker Go client.

param url:

The Docker daemon address as the full URL string (e.g., "unix:///var/run/docker.sock", "tcp://127.0.0.1:2375", "npipe:////./pipe/docker_engine", "ssh://user@host:port"). Takes highest precedence when specified. Refer to SSH Connections for more details about SSH transports in the URL.

param connector:

Custom aiohttp.BaseConnector implementation to establish new connections to the docker host. If provided, it will be used instead of creating a connector based on the url value. A caller-supplied connector is owned by the caller and is not closed by close().

param session:

Custom aiohttp.ClientSession. If None, a new session will be created with the connector and timeout settings. The timeout configuration in this object is ignored by the timeout argument. A caller-supplied session is owned by the caller and is not closed by close().

param timeout:

aiohttp.ClientTimeout configuration for API requests. If None, there is no timeout at all.

param ssl_context:

SSL context for HTTPS connections. If None and DOCKER_TLS_VERIFY is set, will create a context using DOCKER_CERT_PATH certificates.

param api_version:

Pin the Docker API version (e.g., “v1.43”). Use “auto” to automatically detect the API version from the daemon.

param context:

Docker context name to use (e.g., “production”, “staging”). When specified, loads the endpoint configuration from the named context in ~/.docker/contexts/. Overrides all environment variables (DOCKER_HOST, DOCKER_CONTEXT) and config file settings.

raises ValueError:

Raised if the docker host cannot be determined, if both url and connector are incompatible, or if api_version format is invalid.

raises OSError:

On Windows, if named pipe access fails unexpectedly.

async auth(**credentials: Any) → dict[str, Any][source]

Authenticate with Docker registry.

Validates registry credentials and returns authentication information.

Parameters:

credentials –

Registry authentication credentials. Typically includes:

  • username (str): Registry username

  • password (str): Registry password

  • serveraddress (str, optional): Registry server address without a protocol

If you have an identity token issued in prior, you may pass identitytoken only.

Returns:

Authentication response from the Docker daemon, including:

  • Status (str): A string message like “Login Succeeded”

  • IdentityToken (str): The identity token

Raises:

DockerError – If authentication fails or credentials are invalid.

async close() → None[source]

Close the Docker client and release resources.

Stops the event monitoring and closes the underlying aiohttp session, releasing all associated resources including connections.

Only the session and/or connector that this Docker instance created itself are closed; caller-supplied session or connector objects are left untouched. Calling this method multiple times is safe.

async version() → dict[str, Any][source]

Get Docker daemon version information.

Retrieves version details about the Docker daemon including API version, OS, architecture, and component versions.

Returns:

A dict containing version information with keys like:

  • Version (str): Docker version

  • ApiVersion (str): API version

  • Os (str): Operating system

  • Arch (str): Architecture

  • KernelVersion (str): Kernel version

  • GitCommit (str): Git commit hash

and additional component-specific information.

Raises:

DockerError – If the request fails or daemon is unreachable.