Bicep Environment Setup

A proper development environment makes Bicep coding faster, error-free, and enjoyable. This topic covers every tool needed to write, validate, and deploy Bicep templates from a local machine. The setup takes less than 15 minutes and works on Windows, macOS, and Linux.

Tools Required for Bicep Development

Four tools form the complete Bicep development environment:

+--------------------------------------------------+
|         Bicep Development Environment            |
+------------------+-------------------------------+
|  Tool            |  Purpose                      |
+------------------+-------------------------------+
|  Azure CLI       |  Deploy Bicep to Azure        |
|  Bicep CLI       |  Compile and validate Bicep   |
|  VS Code         |  Write and edit Bicep files   |
|  Bicep Extension |  IntelliSense and linting     |
+------------------+-------------------------------+

Azure CLI is the most important tool. It handles authentication with Azure and runs deployments. The Bicep CLI comes bundled with Azure CLI starting from version 2.20.0, so installing Azure CLI is usually enough to get Bicep working.

Step 1 – Install Azure CLI

Azure CLI is available for all major operating systems. Download it from the official Microsoft documentation page or use the commands below.

Windows Installation

Download the MSI installer from the Azure CLI official page and run it. After installation, open PowerShell or Command Prompt and verify with:

az --version

macOS Installation

Use Homebrew to install Azure CLI on macOS:

brew update && brew install azure-cli

Linux (Ubuntu/Debian) Installation

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

After installation, check the version to confirm it installed correctly:

az --version

The output shows the Azure CLI version and the Bicep version. A successful output looks like this:

azure-cli                         2.58.0
bicep                             0.25.53

Step 2 – Install or Update Bicep CLI

Azure CLI includes Bicep, but it may not always be the latest version. Use this command to install or upgrade Bicep to the newest version:

az bicep install

To upgrade an existing Bicep installation:

az bicep upgrade

To check the installed Bicep version separately:

az bicep version

Standalone Bicep CLI (Optional)

For teams that do not use Azure CLI at all, Microsoft also offers a standalone Bicep binary. Download it from the Bicep GitHub releases page. This option suits scenarios where only Bicep compilation is needed without Azure deployment.

Step 3 – Sign In to Azure

Before deploying anything, authenticate Azure CLI with an Azure account. Run this command and follow the browser login prompt:

az login

After login, Azure CLI lists all available subscriptions. To set a specific subscription as the default (replace the ID with the actual subscription ID):

az account set --subscription "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Confirm the active subscription:

az account show

Step 4 – Install Visual Studio Code

VS Code is the recommended editor for Bicep. Download it from the official VS Code website. The editor is free, lightweight, and available for Windows, macOS, and Linux.

VS Code without any extensions can edit Bicep files, but adding the official Bicep extension unlocks powerful productivity features.

Step 5 – Install the Bicep VS Code Extension

Open VS Code, press Ctrl+Shift+X (or Cmd+Shift+X on Mac) to open the Extensions panel. Search for Bicep and install the extension published by Microsoft.

The Bicep extension provides:

+----------------------------------------------------+
|              Bicep VS Code Extension               |
+--------------------+-------------------------------+
|  Feature           |  What It Does                 |
+--------------------+-------------------------------+
|  IntelliSense      |  Suggests resource types,     |
|                    |  properties, and values       |
+--------------------+-------------------------------+
|  Error Highlights  |  Underlines mistakes in       |
|                    |  red before deployment        |
+--------------------+-------------------------------+
|  Code Snippets     |  Types resource skeletons     |
|                    |  with a few keystrokes        |
+--------------------+-------------------------------+
|  Parameter Hints   |  Shows required and optional  |
|                    |  properties inline            |
+--------------------+-------------------------------+
|  Visualizer        |  Shows a diagram of           |
|                    |  resource relationships       |
+--------------------+-------------------------------+

Step 6 – Create and Test the First Bicep File

Create a new folder on the local machine called bicep-practice. Open it in VS Code using File → Open Folder. Create a new file inside the folder named main.bicep.

Paste the following code into main.bicep:

param location string = 'eastus'

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' = {
  name: 'teststorage${uniqueString(resourceGroup().id)}'
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}

Now compile this file to verify Bicep is working correctly. Open a terminal in VS Code (Ctrl+`) and run:

az bicep build --file main.bicep

If everything is set up correctly, a file named main.json appears in the same folder. That file is the compiled ARM template. This confirms Bicep is installed and working.

Step 7 – Create a Resource Group for Practice

All Azure resources live inside a Resource Group. Create a practice resource group to use throughout this course:

az group create --name bicep-practice-rg --location eastus

Confirm the resource group was created:

az group list --output table

Environment Setup Diagram – Complete Flow

 Developer Machine
+----------------------------------------------------------+
|                                                          |
|   VS Code  ──► Bicep Extension (IntelliSense + Lint)     |
|      |                                                   |
|      ▼                                                   |
|   main.bicep (write code here)                           |
|      |                                                   |
|      ▼                                                   |
|   Azure CLI  ──► az bicep build  (compile to JSON)       |
|      |                                                   |
|      ▼                                                   |
|   az deployment group create  (deploy to Azure)          |
|      |                                                   |
+------|---------------------------------------------------+
       |
       ▼
  Azure Cloud ──► Resource Group ──► Resources Created

Useful Azure CLI Commands for Daily Use

Troubleshooting Common Setup Issues

Issue: az command not found after installation

Close and reopen the terminal. The system path may not have refreshed yet. On Windows, try opening a new PowerShell window as Administrator.

Issue: Bicep version is outdated

Run az bicep upgrade to fetch the latest version. If that fails, run az bicep install first.

Issue: Login fails or subscription not found

Run az logout then az login again. If working behind a corporate proxy, configure Azure CLI proxy settings using the HTTPS_PROXY environment variable.

Summary

The Bicep development environment consists of Azure CLI for deployment, the Bicep CLI for compilation, VS Code for editing, and the Bicep extension for IntelliSense and error detection. With all four tools installed and a test file compiled successfully, the environment is ready. The next step is understanding how a Bicep file is structured internally.