Class: DockerClient

This class provides the primary interface for interacting with the Docker Engine. It exposes methods for managing Docker objects such as containers, images, networks, volumes, and more.

Initialization

The DockerClient object can be instantiated using the following:

from docker import DockerClient
          
          client = DockerClient(base_url='unix://var/run/docker.sock', version='auto')
          

Arguments:

• base_url: The URL of the Docker Engine. Defaults to unix://var/run/docker.sock for local Docker installations.
• version: The Docker API version to use. Defaults to auto, which automatically selects the latest supported version.

Methods

The DockerClient class provides numerous methods for interacting with Docker, categorized by the object type they manage:

Container Management

• containers.list(all=False, filters=None, **kwargs): Returns a list of container objects, optionally filtering by criteria.

  • all: Include stopped containers.
  • filters: A dictionary of filters to apply to the results. See Docker documentation for a complete list of supported filters.
  • **kwargs: Additional arguments to pass to the Docker API.

  Example: List all containers with the name “my-container”

  containers = client.containers.list(filters={'name': 'my-container'})
            

• containers.run(image, command=None, detach=False, **kwargs): Creates and starts a new container.

  • image: The Docker image to use for the container.
  • command: The command to run in the container.
  • detach: If True, run the container in detached mode.
  • **kwargs: Additional arguments to pass to the Docker API.

  Example: Run a container from the “nginx” image, running the “nginx” command:

  container = client.containers.run("nginx", command=["nginx"], detach=True)
            

• containers.get(container_id): Returns a single container object by its ID.

  • container_id: The ID of the container.

  Example: Get the container with ID “1234567890abcdef”

  container = client.containers.get("1234567890abcdef")
            

• containers.create(image, command=None, detach=False, **kwargs): Creates a new container without starting it.

  • image: The Docker image to use for the container.
  • command: The command to run in the container.
  • detach: If True, run the container in detached mode.
  • **kwargs: Additional arguments to pass to the Docker API.

  Example: Create a new container from the “nginx” image, without starting it:

  container = client.containers.create("nginx", command=["nginx"])
            

Image Management

• images.list(name=None, **kwargs): Returns a list of image objects, optionally filtered by name.

  • name: The name of the image to filter by.
  • **kwargs: Additional arguments to pass to the Docker API.

  Example: List all images with the name “nginx”

  images = client.images.list(name="nginx")
            

• images.pull(repository, tag=None, **kwargs): Pulls an image from a registry.

  • repository: The name of the repository to pull from.
  • tag: The tag of the image to pull.
  • **kwargs: Additional arguments to pass to the Docker API.

  Example: Pull the “latest” tag of the “nginx” image from Docker Hub:

  client.images.pull("nginx", tag="latest")
            

• images.build(path=None, **kwargs): Builds a new image from a Dockerfile.

  • path: The path to the Dockerfile.
  • **kwargs: Additional arguments to pass to the Docker API.

  Example: Build an image from a Dockerfile located at “Dockerfile”:

  client.images.build(path="Dockerfile")
            

Network Management

• networks.list(names=None, **kwargs): Returns a list of network objects, optionally filtering by name.

  • names: A list of network names to filter by.
  • **kwargs: Additional arguments to pass to the Docker API.

  Example: List all networks with the name “my-network”

  networks = client.networks.list(names=["my-network"])
            

• networks.create(name, **kwargs): Creates a new network.

  • name: The name of the network to create.
  • **kwargs: Additional arguments to pass to the Docker API.

  Example: Create a new network named “my-network”

  network = client.networks.create("my-network")
            

Volume Management

• volumes.list(**kwargs): Returns a list of volume objects.

  • **kwargs: Additional arguments to pass to the Docker API.

  Example: List all volumes:

  volumes = client.volumes.list()
            

• volumes.create(name=None, driver=None, **kwargs): Creates a new volume.

  • name: The name of the volume to create.
  • driver: The name of the volume driver to use.
  • **kwargs: Additional arguments to pass to the Docker API.

  Example: Create a new volume named “my-volume” using the “local” driver:

  volume = client.volumes.create(name="my-volume", driver="local")
            

Other Methods

• info(**kwargs): Returns information about the Docker Engine.

  • **kwargs: Additional arguments to pass to the Docker API.

  Example: Get information about the Docker Engine:

  engine_info = client.info()
            

• close(): Closes the connection to the Docker Engine.

  Example: Close the connection to the Docker Engine:

  client.close()
            

Examples

• Run a container from the “nginx” image:

  from docker import DockerClient
            
            client = DockerClient()
            
            container = client.containers.run("nginx", detach=True)
            

• Pull the “latest” tag of the “nginx” image from Docker Hub:

  from docker import DockerClient
            
            client = DockerClient()
            
            client.images.pull("nginx", tag="latest")
            

• Build an image from a Dockerfile located at “Dockerfile”:

  from docker import DockerClient
            
            client = DockerClient()
            
            client.images.build(path="Dockerfile")
            

Notes

• The DockerClient class provides a high-level interface for interacting with the Docker Engine. It offers methods for managing containers, images, networks, volumes, and more.
• For a complete list of available methods and their arguments, refer to the Docker Python library documentation.
• This outline is intended as a starting point for using the DockerClient class. It provides basic examples for common tasks. For more complex scenarios, refer to the Docker Python library documentation for detailed information and further examples.