--- layout: Conceptual title: Install Azure Cosmos DB Shell - Azure Cosmos DB | Microsoft Learn canonicalUrl: https://learn.microsoft.com/en-us/azure/cosmos-db/shell/install uhfHeaderId: MSDocsHeader-NoSQL permissioned-type: public recommendations: true recommendation_types: - Training - Certification breadcrumb_path: ../../breadcrumb/azure-nosql/toc.json feedback_system: Standard feedback_product_url: https://feedback.azure.com/d365community/forum/3002b3be-0d25-ec11-b6e6-000d3a4f0858 feedback_help_link_url: /answers/tags/187/azure-cosmos-db/ feedback_help_link_type: get-help-at-qna ms.service: azure-cosmos-db ms.subservice: nosql ms.reviewer: mjbrown ms.author: sasinnat author: sajeetharan description: Step-by-step guide to install Azure Cosmos DB Shell using VS Code Marketplace, NuGet package, or self-contained binaries. ms.topic: how-to ms.date: 2026-10-19T00:00:00.0000000Z ai-usage: ai-assisted locale: en-us document_id: dec0b3ba-6f1a-e22f-dd14-30886ea9530b document_version_independent_id: dec0b3ba-6f1a-e22f-dd14-30886ea9530b updated_at: 2026-10-29T12:08:00.0000000Z original_content_git_url: https://github.com/MicrosoftDocs/nosql-docs-pr/blob/live/azure/cosmos-db/shell/install.md gitcommit: https://github.com/MicrosoftDocs/nosql-docs-pr/blob/d544fbd677e5c098756dbf81dcc8b6ff167255c1/azure/cosmos-db/shell/install.md git_commit_id: d544fbd677e5c098756dbf81dcc8b6ff167255c1 site_name: Docs depot_name: Learn.azure-nosql page_type: conceptual toc_rel: ../toc.json word_count: 677 asset_id: cosmos-db/shell/install moniker_range_name: monikers: [] item_type: Content source_path: azure/cosmos-db/shell/install.md cmProducts: - https://authoring-docs-microsoft.poolparty.biz/devrel/911a44a7-2f6c-477c-810f-dc8b7d425cce - https://authoring-docs-microsoft.poolparty.biz/devrel/cd668c2f-f5b3-4573-8ad1-019570e3e2db - https://authoring-docs-microsoft.poolparty.biz/devrel/bcbcbad5-4208-4783-8035-8481272c98b8 spProducts: - https://authoring-docs-microsoft.poolparty.biz/devrel/14f2b9d5-6f06-45a8-ac5f-313eaa351153 - https://authoring-docs-microsoft.poolparty.biz/devrel/cc82e69d-afbe-4554-9f4c-6705fc860c42 - https://authoring-docs-microsoft.poolparty.biz/devrel/43b2e5aa-8a6d-4de2-a252-692232e5edc8 platformId: 203f2604-7f23-b439-3e54-49ab18aac6d7 --- # Install Azure Cosmos DB Shell - Azure Cosmos DB | Microsoft Learn Azure Cosmos DB Shell is available through three distribution methods. Choose the one that best fits your workflow. ## Option 1: VS Code extension (recommended) The VS Code extension provides seamless integration with the code editor. ### Method 1a: Install from VS Code Marketplace 1. **Open VS Code** - Launch Visual Studio Code on your machine 2. **Open Extensions Marketplace** - Click the Extensions icon (Ctrl+Shift+X / Cmd+Shift+X) - Or go to View > Extensions 3. **Search for Cosmos DB** - Type "Cosmos DB" in the search box - Look for the "Azure Cosmos DB" extension by Microsoft 4. **Install the Extension** - Click the Install button - Wait for installation to complete 5. **Verify Installation** - The extension should appear in your installed extensions list - You can now access Cosmos DB Shell from the command palette ### Method 1b: Install from VSIX file 1. **Download Extension** - Download `vscode-cosmosdb-0.33.3.vsix` (or latest version) from the releases 2. **Install Extension** - Open VS Code - Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X) - Click the "..." menu and select "Install from VSIX" - Select the downloaded file 3. **Complete Installation** - Wait for the installation to finish - Reload VS Code if prompted ### VS Code extension requirements - **VS Code Version**: 1.85 or later - **Supported Platforms**: Windows, macOS, Linux - **Disk Space**: ~50 MB For detailed VS Code integration features, see [Visual Studio Code Extension Setup](visual-studio-code). ## Option 2: NuGet package (.NET global tool) Install as a .NET global tool for command-line access. ### Prerequisites - **.NET SDK**: Version 10.0 or later - **Platform Support**: Windows, macOS (Intel and Apple Silicon), Linux (x64 and ARM) ### Installation steps 1. **Open Terminal or Command Prompt** - Windows: Open Command Prompt or PowerShell - macOS/Linux: Open Terminal 2. **Install Global Tool** ```bash dotnet tool install --global CosmosDBShell --prerelease ``` 3. **Verify Installation** ```bash cosmosdbshell --version ``` ### Update to latest version ```bash dotnet tool update --global CosmosDBShell --prerelease ``` ### Uninstall ```bash dotnet tool uninstall --global CosmosDBShell ``` ### Package details - **Package Name**: CosmosDBShell - **Version**: 1.0.213-preview - **NuGet URL**: [CosmosDBShell on NuGet.org](https://www.nuget.org/packages/CosmosDBShell/1.0.213-preview) - **License**: MIT ## Option 3: Self-contained binary (no .NET required) Download and extract a self-contained binary for your platform. ### Prerequisites - No runtime requirements (includes .NET runtime) - Sufficient disk space (~200 MB) ### Installation steps 1. **Download** - Choose your platform: - **Windows (x64)**: `cosmosdbshell-win-x64.zip` - **Windows (ARM)**: `cosmosdbshell-win-arm64.zip` - **macOS (Intel)**: `cosmosdbshell-macos-x64.tar.gz` - **macOS (Apple Silicon)**: `cosmosdbshell-macos-arm64.tar.gz` - **Linux (x64)**: `cosmosdbshell-linux-x64.tar.gz` - **Linux (ARM64)**: `cosmosdbshell-linux-arm64.tar.gz` 2. **Extract Archive** **Windows:** ```powershell Expand-Archive -Path cosmosdbshell-win-x64.zip -DestinationPath "C:\Program Files\CosmosDBShell" ``` **macOS/Linux:** ```bash mkdir -p ~/cosmosdbshell tar -xzf cosmosdbshell-macos-x64.tar.gz -C ~/cosmosdbshell ``` 3. **Add to PATH (Optional)** **Windows:** - Add `C:\Program Files\CosmosDBShell` to your system PATH - Or use the full path: `C:\Program Files\CosmosDBShell\cosmosdbshell.exe` **macOS/Linux:** ```bash export PATH="$HOME/cosmosdbshell:$PATH" # Add to ~/.bashrc or ~/.zshrc for persistence ``` 4. **Run** ```bash cosmosdbshell ``` ## Verification ### Test your installation 1. **For NuGet Installation:** ```bash cosmosdbshell --version ``` 2. **For Binary Installation:** ```bash ./cosmosdbshell --version ``` 3. **For VS Code Extension:** - Open the command palette (Ctrl+Shift+P / Cmd+Shift+P) - Type "Cosmos DB Shell" - You should see Cosmos DB Shell commands ## Troubleshooting ### "Command not found" (NuGet installation) - Ensure .NET SDK 10.0+ is installed: `dotnet --version` - Restart your terminal after installation - Check that `$HOME/.dotnet/tools` is in your PATH ### "File not found" (binary installation) - Verify the archive extracted successfully - Check file permissions: `chmod +x cosmosdbshell` (macOS/Linux) - Use the full path to the executable ### VS Code extension not appearing - Ensure VS Code version is 1.85 or later - Restart VS Code - Check the Extensions marketplace for the "Azure Cosmos DB" extension ## AI tools Use these actions to discuss installation with your assistant. For documentation-only retrieval, use the [Microsoft Learn MCP server](/en-us/training/support/mcp). For a compact guide index, use the [Shell documentation index (`llms.txt`)](llms.txt). The index doesn't change crawler permissions or guarantee retrieval. Shell MCP requires separate setup and can read or change data under the configured permissions, so review tool calls before approving them. Don't share credentials or sensitive data. > > **[Connect your AI agent](/en-us/azure/cosmos-db/shell/model-context-protocol-setup)** Configure Shell MCP after installing the shell. > > **[Read as Markdown](/en-us/azure/cosmos-db/shell/install?accept=text/markdown)** Open a text version to copy into your assistant. > > **[Ask ChatGPT](https://chatgpt.com/?hint=search&q=Read%20https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fazure%2Fcosmos-db%2Fshell%2Finstall%20and%20help%20me%20install%20Shell.%20Ask%20which%20platform%20and%20installation%20method%20I%20use.%20Cite%20the%20source%20and%20state%20if%20you%20cannot%20access%20it.)** Choose installation steps for your platform. > > **[Ask Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fazure%2Fcosmos-db%2Fshell%2Finstall%20and%20help%20me%20install%20Shell.%20Ask%20which%20platform%20and%20installation%20method%20I%20use.%20Cite%20the%20source%20and%20state%20if%20you%20cannot%20access%20it.)** Choose installation steps for your platform. ChatGPT and Claude receive only the public article URL and a starter prompt. You might need to sign in. If retrieval fails, copy the Markdown text. These links don't configure database access.