Azure Cosmos DB エミュレーターの使い方｜vNextのDocker起動とWindows版の選び方

Azure Cosmos DB エミュレーターは、Azureのサブスクリプションも課金も無しにCosmos DBをローカルで動かすための開発用ツールです。現在は「Windows版」「旧Linux版（Docker）」「vNext（Docker）」の3系統が並んでおり、どれを選ぶかで対応APIや動くCPU、CIでの組み方が変わります。この記事では、2026年9月時点のMicrosoft Learnとコンテナレジストリの内容をもとに、系統ごとの違いから起動・接続の手順、CIへの組み込み方までを説明します。

まとめ｜Cosmos DB エミュレーターの選び方と要点

• Mac（Apple Silicon）やARMマシンで使うならvNext一択です。イメージは mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest で、2026年6月2日にGAが発表され、x64とARM64の両方で動きます。
• vNextが対応するのはAPI for NoSQLのゲートウェイモードだけです。MongoDB・Cassandra・Gremlin・TableのAPIを試すならWindows版、MongoDB APIだけなら旧Linux版の mongodb タグを使います。
• vNextは既定でHTTPで起動します。.NETとJavaのSDKはHTTPモードに対応していないため、--protocol https を付けて起動します。
• エンドポイントは localhost:8081、キーは既定では共通の公開キーで、起動時に独自キーを指定することもできます。エミュレーターは開発・テスト用で、本番用途には適しません。
• RUの計測、ストアドプロシージャ・トリガー・UDF、カスタムインデックスの効果はvNextでは確認できません。これらの確認はクラウドのアカウントで行います。
• GitHub Actionsでは、windows-latest ランナーにWindows版が入っているほか、ubuntu-latest ではvNextをサービスコンテナとして起動できます。

エミュレーター3系統の違いと選び方

Microsoft Learnのエミュレーター概要・Linuxベースのエミュレーター（vNext）と、Microsoft Artifact Registry（MCR）のタグ一覧を突き合わせると、2026年9月時点で配布されている系統は次の3つです。

選び方の基準は「動かすマシン」と「使うAPI」の2つです。公式の概要ページには「Linuxベースのエミュレーターは、Apple siliconやMicrosoftのARMチップを搭載した開発マシンをサポートしない」という注意書きがあります。これは旧Linux版の話で、MCRの latest タグは現在もamd64のマニフェストしか持っていません。一方、vnext-latest はamd64とarm64のマルチアーキテクチャイメージです。Apple SiliconでNoSQLをローカル開発する場合はvNextを選びます。ただし、Intel MacでMongoDB APIを検証する場合など、旧Linux版が選択肢になる用途もあります。

Cassandra・Gremlin・Tableのエンドポイントを起動できるのはWindows版だけで、Docker版はこの3つに非対応と明記されています。

vNextをDockerで起動する手順

docker runの基本形とポート8081・8080・1234

公式ドキュメントどおりの起動コマンドは次のとおりです。以降のHTTPS版・永続化版は別の起動例なので、切り替える前に、この例で起動したコンテナを停止して同じホストポートを空けてください。

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

docker run --detach \
  --publish 8081:8081 --publish 8080:8080 --publish 1234:1234 \
  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

3つのポートはそれぞれ役割が違います。

• 8081：Cosmos DBのゲートウェイエンドポイント（SDKの接続先）
• 8080：ヘルスプローブ。/alive・/ready・/status の3つを返します
• 1234：Data Explorer（ブラウザで開く管理画面）

起動完了の判定には、ログの「System is now fully ready to accept requests」ではなく http://localhost:8080/ready を使います。このログ文言は互換性のために残されているだけで、将来削除される可能性があると公式に書かれています。Data Explorerはゲートウェイより数秒遅れて立ち上がります。

HTTPSモードと証明書の扱い

vNextは既定でHTTPで起動します。PythonやNode.jsのSDKは http://localhost:8081 にそのまま接続できますが、.NETとJavaのSDKはHTTPモードに対応していません。この2言語で使う場合は起動引数でHTTPSに切り替えます。

docker run --detach \
  --publish 8081:8081 --publish 8080:8080 --publish 1234:1234 \
  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest --protocol https

Javaではさらに、エミュレーターの自己署名証明書をJDKのトラストストアに登録する必要があります。openssl s_client -connect localhost:8081 </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cosmos_emulator.cert で証明書をファイルに保存し、keytool -cacerts -importcert -alias cosmos_emulator -file 証明書ファイル で取り込みます（パスワードの既定値は changeit）。データボリュームを永続化したままHTTPSで起動すると、証明書は起動のたびに自動で再生成されます。

旧Linux版は証明書を https://localhost:8081/_explorer/emulator.pem で配布しています。curl --insecure で取得し、Ubuntuなら update-ca-certificates、Windowsなら certutil -f -addstore "Root" で登録するのが公式の手順です。

vNextの設定項目とデータの永続化

vNextの設定は起動引数か環境変数で渡します。よく使うものを抜き出しました。

コンテナを止めてもデータを残すには、ホストのディレクトリを /data にマウントします。

mkdir -p ./cosmos-data
docker run --rm -p 8081:8081 \
  -v "$(pwd)/cosmos-data:/data" \
  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

ENABLE_INIT_DATA=true を付けると、/init 直下の .csh ファイルが名前順に実行され、データベース・コンテナ・初期データを作ってからリクエストを受け付けます。ファイル名に 01- のような連番を付けて順序を固定し、既に /data にデータがあれば初期化は省略されます。検索でよく引かれる AZURE_COSMOS_EMULATOR_PARTITION_COUNT・AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE・AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE は旧Linux版の環境変数で、vNextの設定表には載っていません。vNextで永続化したい場合は、これらではなく上記のマウントを使います。

Windows版のインストールと起動オプション

Windows版のダウンロード先と配布バージョン

Windows版は https://aka.ms/cosmosdb-emulator からMSIを取得してインストールします。対応OSは64ビット版のWindows 10・Windows 11・Windows Server 2019で、RAM 2GBと空きディスク10GBが最低要件です。インストール先は %ProgramFiles%\Azure Cosmos DB Emulator で、スタートメニューから起動すると https://localhost:8081/_explorer/index.html のData Explorerが開きます。ローカル版は証明書を自動でインポートするため、追加の設定は不要です。

バージョンの確認では注意が必要です。公式リリースノートの「Latest version」は2024年11月18日の 2.14.21 のまま更新されていません。一方、同じ aka.ms/cosmosdb-emulator からMSIを入れているGitHubホストランナーのイメージ一覧（windows-2025／windows-2022、2026年9月7日版）には「Azure CosmosDb Emulator 2.14.28.0」と記載されています。サポート対象は最新版だけと明記されているので、リリースノートの番号ではなく、配布元から取得した実物のバージョンで判断してください。

コマンドライン引数とPowerShellモジュール

実行ファイル Microsoft.Azure.Cosmos.Emulator.exe に引数を渡すと、起動方法を変えられます（全引数はWindowsエミュレーターのコマンドライン リファレンスを参照）。CIや検証でよく使うのは次の引数です。

スクリプトから扱う場合は、同梱のPowerShellモジュールを読み込みます。Start-CosmosDbEmulator は既定で受付可能になるまで待機し、-NoWait を付けると起動直後に戻ります。

Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
Start-CosmosDbEmulator -NoUI
Get-CosmosDbEmulatorStatus

データの保存先は既定で %LOCALAPPDATA%\CosmosDBEmulator です。コンテナが壊れた、パーティション数を変えたい、といった場合は /ResetDataPath で初期化してから起動し直します。保存済みのデータはすべて消えるため、必要なデータは先に退避してください。

SDKからの接続と固定キー

エミュレーターには固定のアカウントが1つだけ用意されており、既定ではこの資格情報以外では接続できません。

エンドポイント: https://localhost:8081/
キー: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

このキーは公開情報ですが、コードに直接書くと本番の接続先との切り替えで事故が起きやすくなります。接続文字列は環境変数から読み込みます。次のコードは、MicrosoftのGitHub Actions用サンプル（Python）と同じ書き方です。

import os
from azure.cosmos import CosmosClient, PartitionKey

# vNext（HTTP）の例:
# AccountEndpoint=http://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
client = CosmosClient.from_connection_string(os.environ["COSMOSDB_CONNECTION_STRING"])

database = client.create_database_if_not_exists(id="appdb")
container = database.create_container_if_not_exists(
    id="users",
    partition_key=PartitionKey(path="/id"),
)
container.upsert_item({"id": "42", "email": "[email protected]"})

HTTPS版（旧Linux版・Windows版・vNextのHTTPS起動）に接続するとき、証明書を登録していないとSSLエラーになります。SDKの検証を無効にする前に、上の手順で証明書を登録してください。Pythonの仮想環境では、OSの証明書ストアではなく certifi の cacert.pem が参照されている場合があります。vNextはゲートウェイモードしか提供しないため、.NETやJavaのSDKで直接モードを既定にしている場合は、接続モードをゲートウェイに変更してください。Cosmos DBのデータ操作そのものはAzure Cosmos DBで行うCRUD操作で詳しく扱っています。

クラウド版との差分とエミュレーターで検証できないこと

エミュレーターで通ったテストが、クラウドでも同じように動くとは限りません。公式ドキュメントが挙げている差分は次のとおりです。

• スループットはプロビジョニング型のみで、サーバーレスは再現できません。
• インスタンスは1つだけで、複数リージョンへのレプリケーションやスケールアウトはできません。
• Windows版は、400 RU/sの固定サイズコンテナなら10個、無制限サイズなら5個までを想定しています。これを超えても作成はできますが、性能が落ちることがあります。
• Windows版の整合性レベルはSessionとStrongだけで、しかも実際の整合性制御は行わず、設定値を記録するだけです。
• Windows版ではアイテムのidが254文字までに制限されます。1クエリあたりのJOINは最大5つです。

vNextはさらに対応範囲が狭くなります。機能表を見ると、Request Units・コンテナのスループット取得／変更・パーティションをまたぐ並列クエリは「未実装」です。ストアドプロシージャ・トリガー・UDFは「対応予定なし」となっています。カスタムインデックスポリシーとコンテナ更新は「No-op」で、リクエストは成功を返しますが、実際には何も実行されません。インデックスポリシーを書き換えても、クエリは速くなりません。既知の制限として、.NET SDKのバルク実行にも対応していません。

検証内容に応じて、vNext・Windows版・クラウドを次のように使い分けます。

• RU消費量の見積もりやパーティションキー設計の性能評価：vNextはRUを返さず、Windows版もクラウドの物理パーティション構成を再現しません。
• ストアドプロシージャに依存する処理のテスト：vNextでは動かないため、Windows版かクラウドで確認します。
• 整合性レベルの違いによる挙動の検証：エミュレーターは設定値を記録するだけで、実際の整合性制御は行いません。

これらは、検証用のCosmos DBアカウントで確かめます。RU課金やAPIの選び方はAzure Cosmos DB for NoSQLとは｜API選定・RU料金・整合性・ベクトル検索にまとめています。

CI/CDパイプラインでの使い方

GitHub Actions（ubuntuのサービスコンテナとwindows-latest）

Linuxランナーでは、vNextをサービスコンテナにすると、コンテナの起動とジョブ終了時の破棄をGitHub Actionsに任せられます。Microsoftの公式サンプル（AzureCosmosDB/cosmosdb-linux-emulator-github-actions）は、ubuntu-latest と ubuntu-24.04-arm のマトリクスでこの構成を採用しています。以下のLinux版・Windows版のYAMLはジョブ部分の抜粋です。使用する方を .github/workflows/test.yml に保存し、最上位に on: [push, pull_request] を追加します。Linux版には /ready の待機処理を加えています。実行対象のpytestまたは.NETのテストは、リポジトリに用意しておきます。

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      cosmosdb:
        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest
        ports:
          - 8081:8081
          - 8080:8080
    env:
      COSMOSDB_CONNECTION_STRING: "AccountEndpoint=http://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Wait for emulator
        run: |
          for i in $(seq 1 60); do
            curl -sf http://localhost:8080/ready && exit 0
            sleep 2
          done
          exit 1
      - run: pip install azure-cosmos pytest
      - run: pytest -v

サービスコンテナには、services.cosmosdb.command で起動引数を渡せます。.NETやJavaでHTTPSが必要な場合は、services.cosmosdb.env に PROTOCOL: https を指定します。サービスコンテナはLinuxランナー専用なので、Windowsランナーでは使えません。

Windows版を使う場合は、windows-latest に最初から入っているエミュレーターをPowerShellで起動します。

jobs:
  test:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - name: Start Azure Cosmos DB emulator
        run: |
          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
          Start-CosmosDbEmulator
      - run: dotnet test

上の例はNoSQL用です。MongoDB・Gremlin・Table APIをテストする場合は、起動コマンドにそれぞれ -EnableMongoDb・-EnableGremlin・-EnableTable を付けて対象APIを有効にします。NoSQLのストアドプロシージャを含むテストもWindows版で実行できます。

Azure DevOps（ビルドタスク廃止後の構成）

Azure DevOpsのCosmos DB Emulatorビルドタスクは、Windows 2016ホストエージェントが2022年4月1日に削除された時点でサポートが終わっています。公式チュートリアルでは代わりに、windows-2019 エージェントでPowerShellタスクを実行する方法を案内しています。ただし、Azure Pipelinesの windows-2019 イメージは2025年12月31日に退役済みで、チュートリアルのYAMLをそのまま使うと動きません。

現在は vmImage: windows-2022 または windows-2025 を指定し、PowerShellタスクで Start-CosmosDbEmulator -NoFirewall -NoUI を実行します。Microsoftホストエージェントのイメージは、GitHub Actionsと同じ actions/runner-images リポジトリで作られています。両イメージのソフトウェア一覧には、どちらもエミュレーター2.14.28.0が記載されています。セルフホストエージェントの場合は、aka.ms/cosmosdb-emulator のMSIを msiexec でサイレントインストールしてから、同じスクリプトを実行します。

Testcontainersの言語別モジュールと既定イメージ

テストコードの中でコンテナを起動・破棄したい場合は、Testcontainersのモジュールが使えます。2026年9月時点の配布物で確認したクラス名は次のとおりです。

Python版の既定イメージは旧Linux版の azure-cosmos-emulator:latest（amd64のみ）で、環境変数 AZURE_COSMOS_EMULATOR_IMAGE で差し替えられます。Apple Silicon上では既定イメージがネイティブに動かない点に注意してください。Testcontainers全般の仕組みと2.0系の移行点はTestcontainersとは？Dockerで作る使い捨てテスト環境と2.0系の移行点を参照してください。

起動・接続トラブルの原因と対処

• Macで旧イメージが起動しない、または極端に遅い：:latest はamd64専用です。:vnext-latest に切り替えます。
• .NET／JavaのSDKがvNextに接続できない：--protocol https を付けて起動し直します。直接モードを使う設定になっていれば、ゲートウェイモードに変更します。
• SSL証明書エラー：証明書をOSやランタイムのストアに登録します（手順はHTTPSモードの節を参照）。
• 大きなクエリでHTTP 500が返る：vNextの QUERY_BUFFER_SIZE_KB（既定4096、最大65536）を増やします。
• テスト開始直後だけ接続に失敗する：起動完了を待たずにテストが走っています。http://localhost:8080/ready が200を返すまで待機します。
• Windows版でコンテナを作りすぎて遅い、または作成に失敗する：/PartitionCount を見直し、/ResetDataPath で初期化してから起動し直します。初期化すると保存済みデータは消えます。

よくある質問

Azure Cosmos DB エミュレーターはMac（M1/M2/M3）で使えますか？

vNext（vnext-latest タグ）なら使えます。arm64のイメージが提供されており、Docker Desktopなどでそのまま起動できます。旧Linux版の latest タグはamd64専用のため、Apple Siliconでは使えません。Docker Desktopの導入はDocker Desktopの導入手順とライセンス境界を参照してください。

エミュレーターの利用は無料ですか？

無料です。Azureのサブスクリプションを作らずに、ローカルで開発とテストができます。ただし、エミュレーターは本番ワークロードでの利用が推奨されていません。

コンテナを停止するとデータは消えますか？

vNextは、docker run --rm で起動したままコンテナを止めるとデータが消えます。残したい場合は、ホストのディレクトリを /data にマウントします。Windows版は %LOCALAPPDATA%\CosmosDBEmulator にデータを保存します。

エミュレーターのキーは変更できますか？

起動中のエミュレーターではキーを再生成できません。別のキーを使う場合は、起動時に指定します。Windows版は /Key や /KeyFile、vNextは KEY_FILE で指定します。Windows版でネットワーク越しにアクセスさせる /AllowNetworkAccess を使う場合は、キーの指定が必須です。

エミュレーターでRU（要求ユニット）を計測できますか？

vNextでは、Request Unitsは未実装です。RU消費量の見積もりは、検証用のCosmos DBアカウントで行ってください。

関連記事

• Azure Cosmos DB for NoSQLとは｜API選定・RU料金・整合性・ベクトル検索
• Azure Cosmos DBで行うCRUD操作：データの挿入・取得・更新・削除の方法
• Testcontainersとは？Dockerで作る使い捨てテスト環境と2.0系の移行点
• Docker Desktopの導入手順とライセンス境界｜4.89系の要件と無料代替
• LocalStackとは？AWSをローカルで動かす手順と有料化後の料金・判断基準