この記事の要点

Python の docker SDK が Docker daemon に接続できないときに出るエラー 原因 5 つ: ① Docker daemon 未起動 ② 権限不足 (Unix socket) ③ DOCKER_HOST 環境変数誤り ④ Docker Desktop 未起動 (Win/Mac) ⑤ WSL2 backend 不整合 対処: sudo systemctl start docker → docker ps で疎通確認 → usermod -aG docker $USER で権限付与 → 再ログイン Windows / Mac は Docker Desktop を起動 + WSL2 統合をオンに CI / コンテナ内から呼ぶときは -v /var/run/docker.sock:/var/run/docker.sock

エラーメッセージ全文

Traceback (most recent call last):
  File "/usr/local/lib/python3.11/site-packages/docker/api/client.py", line 214, in _retrieve_server_version
    return self.version(api_version=False)["ApiVersion"]
  ...
docker.errors.DockerException: Error while fetching server API version: \
    ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))

# Linux で daemon 停止中の典型
# または
docker.errors.DockerException: Error while fetching server API version: \
    ('Connection aborted.', PermissionError(13, 'Permission denied'))

Python コード:

import docker

client = docker.from_env()    # ← ここで落ちる
client.containers.list()

原因の切り分け

エラー詳細	原因	対処
FileNotFoundError(2)	daemon 未起動 or socket パス誤り	対処1: daemon 起動
PermissionError(13)	socket 権限不足 (root or docker グループ要)	対処2: グループに追加
ConnectionRefusedError	TCP listen してないのに DOCKER_HOST=tcp://...	対処3: 環境変数を見直し
Cannot connect to Docker daemon at unix:///var/run/docker.sock	同上	対処1 or 対処2
error during connect: Get http://...:2375/v1.40/version	Windows で Docker Desktop 未起動	対処4

対処1: Docker daemon を起動

# Linux (systemd)
sudo systemctl status docker
sudo systemctl start docker
sudo systemctl enable docker      # 自動起動

# Linux (sysvinit / 古い)
sudo service docker start

# 動作確認
docker ps                          # daemon に繋がれば OK
docker info

対処2: 権限を付与 (docker グループ)

毎回 sudo docker は面倒。docker グループに追加すれば一般ユーザーで叩ける:

# docker グループ作成 (Docker インストール時に通常作成済)
sudo groupadd docker

# 現在ユーザーを docker グループに追加
sudo usermod -aG docker $USER

# グループ反映には ★再ログイン or 新規シェル必須★
exit
# 再 SSH
groups   # docker が含まれているか確認

# テスト
docker run hello-world

注意: docker グループは事実上 root と同等の権限。本番サーバーでは慎重に。

対処3: DOCKER_HOST 環境変数

# 現在の値を確認
echo $DOCKER_HOST
env | grep -i docker

# 誤って tcp:// を指していたら unset
unset DOCKER_HOST
unset DOCKER_CERT_PATH
unset DOCKER_TLS_VERIFY

# 正しい値 (Unix socket = 未設定でよい)
# export DOCKER_HOST=unix:///var/run/docker.sock

# リモート daemon の場合
# export DOCKER_HOST=tcp://10.0.0.5:2376
# export DOCKER_TLS_VERIFY=1
# export DOCKER_CERT_PATH=~/.docker

対処4: Windows / Mac で Docker Desktop を起動

• タスクトレイ / メニューバーで Docker のクジラアイコンを確認
• 停止していたら起動 → 「Docker Desktop is running」を待つ
• Settings → General → Use the WSL 2 based engine をオン (Windows)
• Settings → Resources → WSL Integration → 使う distro をオン
• WSL のシェル内で docker version でサーバ側 (Engine) と通信できるか確認

# Docker Desktop を CLI から起動
Start-Process "C:\Program Files\Docker\Docker\Docker Desktop.exe"

# 状態確認
docker version
docker info

# サービス確認
Get-Service com.docker.service

対処5: WSL2 backend 不整合

# WSL 内で docker が見えるか
which docker
ls -l /var/run/docker.sock

# 見えない場合: Docker Desktop の WSL Integration を切替
# Settings → Resources → WSL Integration → Ubuntu を OFF → ON

# WSL を再起動
# (PowerShell から)
# wsl --shutdown
# wsl

# それでもダメなら socket を直接 export
export DOCKER_HOST=unix:///mnt/wsl/shared-docker/docker.sock

対処6: コンテナ内から docker を呼ぶ (Docker-in-Docker)

CI ランナーや別コンテナから親ホストの docker を呼ぶ場合、socket をマウント:

# 親ホストの docker socket をマウント
docker run --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v $(pwd):/work -w /work \
    python:3.11 \
    python my_script.py

# docker-compose 版
services:
  worker:
    image: python:3.11
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./:/work
    working_dir: /work
    command: python my_script.py

Python 側で接続テスト

import docker

# 1. 環境変数から自動検出
try:
    client = docker.from_env()
    print(client.version())
    print(client.containers.list())
except docker.errors.DockerException as e:
    print("Docker 接続失敗:", e)

# 2. 明示的に socket 指定
client = docker.DockerClient(base_url='unix://var/run/docker.sock')

# 3. リモート daemon (TLS)
client = docker.DockerClient(
    base_url='tcp://10.0.0.5:2376',
    tls=docker.tls.TLSConfig(
        client_cert=('~/.docker/cert.pem', '~/.docker/key.pem'),
        ca_cert='~/.docker/ca.pem',
        verify=True,
    ),
)

セルフチェック表

確認	コマンド	期待出力
daemon 起動	systemctl is-active docker	active
socket 存在	ls -l /var/run/docker.sock	srw-rw---- root docker
所属グループ	groups	docker が含まれる
疎通	docker version	Client + Server の両方表示
Python SDK	python -c "import docker; print(docker.from_env().version())"	バージョン情報

FAQ

Q: なぜ Python なのに Docker daemon を直接呼ぶ？
A: docker SDK は CLI ではなく HTTP API 経由で daemon と通信します。docker コマンドと同じ socket を使うので daemon が要ります。

Q: rootless docker を使っている
A: DOCKER_HOST=unix:///run/user/$UID/docker.sock を export。

Q: GitHub Actions で起きる
A: ubuntu-latest ランナーは docker 入りで動くが、self-hosted の場合は daemon を別途用意。docker:dind サービスを使う方法もあり。