What is the Cosmos DB Emulator and how is it used in development?

The Azure Cosmos DB Emulator is a locally running software that faithfully emulates the Cosmos DB NoSQL API on your development machine. It lets you develop and test Cosmos DB applications without an Azure subscription, without incurring costs, and with full offline capability. The emulator runs as a Windows application or as a Docker container (supporting Linux and macOS via Docker).

Starting the emulator via Docker is the most cross-platform approach:

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

docker run -p 8081:8081 -p 10251-10255:10251-10255 \
  -e AZURE_COSMOS_EMULATOR_PARTITION_COUNT=10 \
  -e AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE=true \
  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

The emulator exposes the same REST endpoint as the cloud service at https://localhost:8081 and uses a well-known fixed key for authentication (the same key is documented publicly and is the same for every installation). Connection string:

AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

Key limitations compared to the cloud service:

• Only supports the NoSQL API — no MongoDB, Cassandra, or Gremlin emulation
• No global distribution simulation
• No SLA guarantees (performance is your local machine's)
• The emulator certificate is self-signed — CI pipelines need to trust it explicitly
• Supports up to 25 fixed containers with simulated partitioning

For integration tests in CI/CD pipelines, the emulator Docker image is commonly used in GitHub Actions or Azure DevOps pipeline steps, giving every pull request its own isolated Cosmos DB environment at zero cost.