Docker API バージョン不一致エラーの対処法と最新版解消手順（2026）

2026年4月24日

Contents

1 Docker API バージョン不一致エラーとは
2 1. クライアント・サーバ側の API バージョン確認手順
- 2.1 1‑1. docker version で一目で把握
- 2.2 1‑2. /info エンドポイントから取得（トラブルシューティング向け）
3 2. バージョン不一致をすぐに解消する方法
4 3. Docker Engine のアップデート手順（Ubuntu/Debian 系）
5 4. CI/CD パイプラインでの安全な Docker-in-Docker 設定
- 5.1 4‑1. GitHub Actions
  - 5.1.1 補足
- 5.2 4‑2. GitLab CI
  - 5.2.1 補足
6 5. バージョン差異が再発しないための運用ガイド
7 6. まとめ

スポンサードリンク

Docker API バージョン不一致エラーとは

Docker クライアント（docker コマンド）と Docker デーモン（dockerd）は それぞれ独立した API バージョン を持ちます。
クライアントがサーバに対してリクエストを送る際、デフォルトではサーバのバージョンを自動的に取得し、互換可能な最も古い API バージョンで通信します。

しかし次のような状況になると 「client and server have different API versions」 というエラーが発生します。

発生日	主な原因
ローカル環境（Docker Desktop, WSL2 等）	`DOCKER_API_VERSION` が手動で設定されている、または古い CLI が残っている
CI/CD ランナー	デフォルトの Docker クライアントがサーバと乖離している
テストフレームワーク（Testcontainers 等）	コンテナ内部から `docker` コマンドを呼び出す際にバージョンが固定されている

1. クライアント・サーバ側の API バージョン確認手順

1‑1. `docker version` で一目で把握

$ docker version --format '{{.Client.APIVersion}} {{.Server.APIVersion}}'
20.10 20.10

$ docker version --format '{{.Client.APIVersion}} {{.Server.APIVersion}}'

20.10 20.10

左側がクライアント、右側がサーバの API バージョンです。
バージョンが一致していれば基本的に問題は起きません。

1‑2. `/info` エンドポイントから取得（トラブルシューティング向け）

$ curl -s --unix-socket /var/run/docker.sock http://localhost/info | \
    jq '.ServerVersion, .APIVersion'
&quot;20.10.14&quot;
&quot;1.41&quot;

$ curl -s --unix-socket /var/run/docker.sock http://localhost/info | \

jq '.ServerVersion, .APIVersion'

"20.10.14"

"1.41"

Windows の PowerShell でも同様に取得できます（Docker Desktop が tcp://localhost:2375 を有効化している場合）:

Invoke-RestMethod -Uri http://localhost:2375/info | Select-Object ServerVersion, APIVersion

1 2	Invoke-RestMethod -Uri http://localhost:2375/info \| Select-Object ServerVersion, APIVersion

2. バージョン不一致をすぐに解消する方法

2‑1. `DOCKER_API_VERSION` 環境変数で固定

# Bash / Zsh
export DOCKER_API_VERSION=1.41

# PowerShell
$Env:DOCKER_API_VERSION = &quot;1.41&quot;

# Bash / Zsh

export DOCKER_API_VERSION=1.41

# PowerShell

$Env:DOCKER_API_VERSION = "1.41"

環境変数はプロセス単位で優先され、クライアント側の自動判定を上書きします。

ポイント
- 変更はそのシェル（または CI ジョブ）だけに有効です。永続化したい場合はシステムのプロファイルに追記してください。

2‑2. `--api-version` フラグでコマンド単位に指定

docker --api-version=1.41 ps -a

1 2	docker --api-version=1.41 ps -a

スクリプトや一部のテストだけ異なるバージョンが必要なときに便利です。
フラグは実行時のみ有効で、設定は残りません。

2‑3. サーバ側で API バージョンを「固定」する手段は存在しない

Docker デーモンの daemon.json に default-api-version といった項目はありません。
サーバが提供できる最小の API バージョンはビルド時に決まりますので、バージョンを下げることはできません。

代替策
- 必要に応じて Docker Engine のダウングレード（パッケージのバージョン指定）を行う。
- クライアント側で上記環境変数／フラグを用いてサーバと合わせる。

3. Docker Engine のアップデート手順（Ubuntu/Debian 系）

3‑1. 現在インストールされているバージョンの確認

$ apt-cache policy docker-ce

1 2	$ apt-cache policy docker-ce

3‑2. 特定バージョンをインストールする例

公式リポジトリから 20.10 系（2024 年時点で安定版）をインストールしたい場合、パッケージ名と完全なバージョン文字列を指定します。以下は 20.10.14 の例です。

sudo apt-get update
sudo apt-get install -y \
    docker-ce=5:20.10.14~3-0~ubuntu-focal \
    docker-ce-cli=5:20.10.14~3-0~ubuntu-focal \
    containerd.io

sudo apt-get update

sudo apt-get install -y \

docker-ce=5:20.10.14~3-0~ubuntu-focal \

docker-ce-cli=5:20.10.14~3-0~ubuntu-focal \

containerd.io

ポイント
- = の後に リポジトリが提供する正確なバージョン文字列 を記述します。27.0.* などのワイルドカードは使用できません。
- バージョンが見つからない場合は、apt-cache madison docker-ce で利用可能な一覧を取得してください。

3‑3. アップデート後に API バージョンを再確認

docker version --format '{{.Server.APIVersion}}'

1 2	docker version --format '{{.Server.APIVersion}}'

4. CI/CD パイプラインでの安全な Docker-in-Docker 設定

Docker-in-Docker（dind）を利用する際は 特権モード と ソケット共有 が必須です。以下は GitHub Actions と GitLab CI の実装例です。

4‑1. GitHub Actions

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      DOCKER_API_VERSION: &quot;1.41&quot;
    services:
      docker:
        image: docker:dind
        privileged: true          # 特権モードでデーモンを起動
        options: --health-cmd &quot;docker info&quot; --health-interval 10s
    steps:
      - uses: actions/checkout@v4
      - name: Set up Docker client
        run: |
          docker version   # 確認用（クライアントはホスト側にインストール済み）
      - name: Run integration tests
        run: ./gradlew test

name: CI

on: [push, pull_request]

jobs:

test:

runs-on: ubuntu-latest

env:

DOCKER_API_VERSION: "1.41"

services:

docker:

image: docker:dind

privileged: true # 特権モードでデーモンを起動

options: --health-cmd "docker info" --health-interval 10s

steps:

- uses: actions/checkout@v4

- name: Set up Docker client

run: |

docker version # 確認用（クライアントはホスト側にインストール済み）

- name: Run integration tests

run: ./gradlew test

補足

privileged: true が無いと dind コンテナ内で dockerd が正常に起動しません。
DOCKER_API_VERSION を環境変数として設定すれば、全ステップが同一 API バージョンで実行されます。

4‑2. GitLab CI

stages:
  - test

variables:
  DOCKER_API_VERSION: &quot;1.41&quot;

test_job:
  image: docker:stable
  services:
    - name: docker:dind
      alias: docker
      command: [&quot;--host=tcp://0.0.0.0:2375&quot;]
      privileged: true
  before_script:
    # ホスト側の Docker クライアントが dind に接続できるようにソケットをマウント
    - export DOCKER_HOST=tcp://docker:2375
    - docker version   # 接続確認
  script:
    - ./gradlew test

stages:

- test

variables:

DOCKER_API_VERSION: "1.41"

test_job:

image: docker:stable

services:

- name: docker:dind

alias: docker

command: ["--host=tcp://0.0.0.0:2375"]

privileged: true

before_script:

# ホスト側の Docker クライアントが dind に接続できるようにソケットをマウント

- export DOCKER_HOST=tcp://docker:2375

- docker version # 接続確認

script:

- ./gradlew test

補足

privileged: true と command: ["--host=tcp://0.0.0.0:2375"] により、外部から TCP ソケットでデーモンにアクセス可能になります。
DOCKER_HOST 環境変数を設定しないと、クライアントはローカルのソケット（存在しません）へ接続しようとして失敗します。

5. バージョン差異が再発しないための運用ガイド

項目	推奨アクション
リリース情報取得	Docker Hub の「Docker Engine」ページの RSS フィードや GitHub の `docker/engine` リポジトリを購読。
自動アップデート	Renovate・Dependabot で `docker-ce` パッケージ更新用 Pull Request を作成し、マージ時に CI が新しい API バージョンでテストできるようスクリプトを走らせる。
バージョン固定	プロジェクトごとに `DOCKER_API_VERSION` を `docker version --format '{{.Server.APIVersion}}'` の出力でロックし、CI の環境変数として宣言する。
ドキュメント更新	API バージョンが変更されたら README などの開発手順を即時更新し、チーム全体に共有する。

6. まとめ

不一致の原因はクライアントとサーバの API バージョン差 にあることをまず確認。
docker version と /info エンドポイントで現在のバージョンを把握する。
即時対策は DOCKER_API_VERSION 環境変数 か --api-version フラグ を使用。
サーバ側で API バージョンを強制的に下げる設定は存在しないため、必要なら Docker Engine のダウングレードを行う。
CI/CD では Docker-in-Docker の特権モードとソケット共有 を正しく設定し、環境変数でバージョンを固定する。
リリース情報の自動取得・パッケージ更新ツールを活用し、バージョン管理を継続的に行う。

上記手順と運用ルールを導入すれば、Docker API バージョン不一致エラーはほぼ防げます。開発・テスト環境の安定性が向上し、リリースサイクルもスムーズになるでしょう。