Docker SDK for Python

Warnings

• breaking 'docker-py' is the old abandoned package (last release 2016). Install 'docker' instead. Both install as 'import docker' which causes confusion. Having both installed simultaneously causes conflicts.
  Fix: pip install docker — not docker-py. Run 'pip uninstall docker-py' if it's installed.
• breaking docker.Client() removed. LLMs and old tutorials use Client(base_url=...) which raises AttributeError.
  Fix: Use docker.from_env() or docker.DockerClient(base_url=...)
• gotcha from_env() raises DockerException on macOS with Docker Desktop if the socket symlink is missing. Error: 'Error while fetching server API version: FileNotFoundError /var/run/docker.sock'
  Fix: Docker Desktop on Mac uses ~/.docker/run/docker.sock. Fix: sudo ln -s ~/.docker/run/docker.sock /var/run/docker.sock. Or use DOCKER_HOST=unix://~/.docker/run/docker.sock
• gotcha from_env() fails with Colima or Podman because they use different socket paths. Error: 'port is required' or 'FileNotFoundError'.
  Fix: Set DOCKER_HOST explicitly: DOCKER_HOST=unix:///Users/user/.colima/default/docker.sock or use DockerClient(base_url=...)
• gotcha containers.run() without detach=True blocks until container exits. Long-running containers will hang the process indefinitely.
  Fix: Always use detach=True for services: client.containers.run('nginx', detach=True)
• gotcha containers.run() with detach=True returns a Container object. containers.run() without detach=True returns bytes (stdout). Different return types for same method.
  Fix: Check detach parameter carefully. With detach=True: container.logs(). Without: output bytes directly.
• gotcha Streams from container.logs(stream=True) or containers.run(stream=True) return a generator of bytes chunks — not a single bytes object.
  Fix: for chunk in container.logs(stream=True): print(chunk.decode())

Install

• pip install docker Python (official SDK)
• pip install 'docker[ssh]' Python (with SSH connection support)

Imports

• from_env / DockerClient

  import docker
  
  # Recommended — reads DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH
  client = docker.from_env()
  
  # Or explicit:
  client = docker.DockerClient(base_url='unix://var/run/docker.sock')
  
  # Run container (blocks until exit)
  output = client.containers.run('ubuntu', 'echo hello')
  print(output)  # b'hello\n'
  
  # Run detached (non-blocking)
  container = client.containers.run('nginx', detach=True)
  print(container.id)
  
  # List running containers
  for c in client.containers.list():
      print(c.name, c.status)

  Install 'docker' not 'docker-py'. The old docker.Client class was removed — use docker.DockerClient or docker.from_env().
• containers.run (detach)

  import docker
  
  client = docker.from_env()
  
  # Non-blocking — returns Container object
  container = client.containers.run(
      'python:3.11',
      'python -c "print(42)"',
      detach=True,
      remove=True  # auto-remove on exit
  )
  
  # Wait for completion and get logs
  container.wait()
  logs = container.logs()
  print(logs)

  containers.run() without detach=True blocks until the container exits and returns stdout. For long-running services always use detach=True.

Quickstart

Docker SDK for Python — run, manage and inspect containers.

# pip install docker
import docker

client = docker.from_env()

# Pull image
client.images.pull('alpine')

# Run and get output (blocking)
output = client.containers.run('alpine', 'echo hello world')
print(output)  # b'hello world\n'

# Run detached service
container = client.containers.run(
    'nginx',
    detach=True,
    ports={'80/tcp': 8080},
    name='my-nginx'
)
print(f'Started: {container.name} ({container.short_id})')

# Inspect
container.reload()
print(container.status)  # 'running'

# Stop and remove
container.stop()
container.remove()

# List all images
for image in client.images.list():
    print(image.tags)