Azure Bicep: a declarative language for deploying Azure resources

What Bicep solves for Azure-only infrastructure teams

Writing raw ARM template JSON by hand is the problem Bicep exists to remove. The README describes Bicep as "an infrastructure-as-code (IaC) programming language that uses declarative syntax to deploy Azure resources," and the FAQ claims a "much simpler syntax compared to equivalent ARM Template JSON." That comparison is the whole pitch: you keep ARM as the deployment engine but stop authoring its JSON directly.

The audience is narrow and specific. If you deploy to Azure and nothing else, Bicep is a drop-in authoring layer. If you need one tool that also provisions AWS, GCP or Kubernetes, this is not it. The README's non-goals state plainly that Bicep is not "a general-purpose language to meet any need" and that it does not "provide a first-class provider model for non-Azure related tasks." The extensibility model exists and supports Microsoft Graph, but the stated intent is to keep official extension points focused on Azure infrastructure or application deployment.

The second constraint worth internalising is that Bicep is not a runtime. The README says you "might still need to do pre or post-Bicep execution tasks in a script or high-level programming language." Teams that expect conditionals, loops and API calls against external systems to live entirely inside the template will be disappointed.

How transpilation to ARM works, and why there is no state file

Bicep is compiled, not interpreted by Azure. The README explains that Azure CLI and the PowerShell Az module have Bicep support built in, so "you can use the standard deployment commands with your `*.bicep` files. The tooling transpiles the code and sends it to ARM on your behalf." The artifact ARM receives is a template it already understands.

That single design decision explains several properties. Because the compiler ships inside tooling you likely already have, there is no separate binary to keep in sync with the deployment path. Because the output is an ARM template, resource coverage follows the ARM control plane rather than a curated provider list. The README makes this explicit as a goal: the language should offer a "transparent abstraction" with "no 'onboarding step' to enable Bicep support for a new resource type or API version." A resource in private preview is deployable the day its ARM API exists.

State is the other half. The FAQ says there are "no state or state files to manage. All state is stored in Azure, so it's easy to collaborate and make changes to resources confidently." This is the sharpest contrast with tools that keep a local or remote state backend. There is nothing to lock, no backend to configure, and no drift between a state file and reality to reconcile before a plan. The trade-off is that you lose the explicit plan artifact those tools produce; validation happens through the language service and the compiler, not through a stored snapshot diff.

Installing the Bicep CLI and deploying a first resource group

The README does not inline installation steps. It points to the install documentation on Microsoft Learn as step one of getting started, and notes that Azure CLI 2.20.0+ and PowerShell Az module 5.6.0+ have Bicep support built in. So the practical route is to install or update one of those two tools, then confirm Bicep is available.

Once the CLI is present, the deployment command from the README is the real test. It takes a Bicep file directly:

az deployment group create -f ./main.bicep -g my-rg

The `-f` flag points at the `.bicep` file and `-g` names the target resource group. The tooling transpiles that file and submits the resulting ARM template, so the output you should expect is an ARM deployment result, not a Bicep-specific one.

For authoring, the README recommends the Bicep VS Code extension, describing it as the way to "author your Bicep code by using the Bicep language service." The extension is where type validation against Azure resource API definitions happens. The README's own tip for newcomers is to install that extension and "deploy a simple resource (like a storage account) to get comfortable with the end-to-end workflow before moving to larger templates."

If you are starting from existing JSON rather than a blank file, the README points to the migration workflow and to decompilation as the way to convert an ARM template into `.bicep` format. Two other resources it names: the Bicep Playground for browser-based experimentation, and the bicep-registry-modules repository for production-ready templates.

Where Bicep is the wrong tool

The non-goals are the honest part of the README, and they map directly onto failure modes.

Multi-cloud provisioning is out. If your estate spans Azure and another cloud, you will run Bicep for one half and something else for the other, which means two authoring models, two review cultures and two sets of tooling in CI. The README does not pretend otherwise; it frames non-Azure provider work as outside the intended scope.

Anything that needs a general-purpose language is out. String manipulation, HTTP calls to external systems, and complex orchestration are not what the declarative syntax is for. The README directs those to scripts around the deployment rather than inside it.

There is also a subtler cost. Because there is no state file and no plan artifact, the confidence you get before a deployment comes from the compiler and the language service rather than from a diff against recorded state. The README's goal list includes giving users "a high level of confidence that their code is 'syntactically valid' before deploying," which is a narrower promise than predicting the resulting change set. Teams migrating from a plan-and-apply workflow should expect to rebuild that habit around what-if style inspection rather than assume it carries over.

Finally, the README is a pointer document, not a manual. Installation, the language reference and the FAQ all live on Microsoft Learn. Anyone expecting the repository to be self-contained will spend their first hour following links.

Bicep compared with Terraform and with raw ARM JSON

The nearest alternative for Azure work is Terraform with the AzureRM provider. The difference is architectural, not cosmetic. Terraform keeps state, either locally or in a remote backend, and uses that state to compute a plan before applying. Bicep has no state at all; the README states that all state is stored in Azure. Terraform's provider model is multi-cloud by construction, while Bicep's stated non-goal is exactly that.

The practical consequence: with Terraform you get an explicit plan artifact and a state file you must secure, lock and migrate. With Bicep you get neither, which removes a class of operational work and also removes the pre-apply diff. Neither is strictly better; they optimise for different things.

The other alternative is staying on ARM template JSON. Bicep does not replace ARM, it feeds it. The FAQ frames the benefit as simpler syntax relative to the equivalent JSON, and the migration path is one-directional in practice: you can decompile an ARM template into Bicep, but the deployment target remains the same. Choosing Bicep over raw JSON costs you nothing at deploy time and gains readability, modules and compiler validation. The reason to stay on JSON is usually tooling that generates or consumes ARM templates directly.

Maintenance, licensing and what upgrading costs you

The repository is not archived, and the last push was on 2026-09-28. Recent releases include v0.47.16 on 2026-09-08, v0.46.1 on 2026-07-30 and v0.45.15 on 2026-07-13. The version numbers move quickly, which is expected for a compiler that tracks Azure resource API definitions.

The upgrade model is mostly invisible to you. Because the CLI and Az module carry Bicep support internally, upgrading Bicep often means upgrading the CLI or module you already use, rather than installing a separate tool. The cost that does land on you is template churn: as the language and its type definitions evolve, files that were valid may produce new warnings. The README's goal of high confidence in syntactic validity before deploying is only as good as the compiler version you are running, so CI should pin or at least report the CLI version it uses.

Licensing is MIT, stated in the repository root. That is permissive and places few obligations on how you use the output. It says nothing about the Azure resources you deploy, which are governed by your Azure agreement, and nothing about the Microsoft Learn documentation or the VS Code extension, which are separate artifacts with their own terms. Treat the MIT grant as covering the repository contents only.

Support is worth noting separately: the FAQ states Bicep is "supported by Microsoft support and 100% free to use." That is a support commitment, not a licence term.

Editorial conclusion

Adopt Bicep if your infrastructure lives in Azure, you already have Azure CLI 2.20.0+ or Az module 5.6.0+, and you want day 0 support for any ARM resource without managing state. Do not adopt it as a multi-cloud or general-purpose provisioning language: the README lists non-Azure provider work as a non-goal, and pre or post-deployment logic still belongs in a script. Before committing, verify that your installed CLI version reports Bicep support and run az bicep build on one existing template to see what the transpiler emits.

Frequently asked questions

Official sources

1. Azure/bicep on GitHub
2. Issues
3. License: MIT
4. README
5. Releases