Import and export blueprint definitions with PowerShell
Article
Important
On July 11, 2026, Blueprints (Preview) will be deprecated. Migrate your existing blueprint definitions and assignments to Template Specs and Deployment Stacks. Blueprint artifacts are to be converted to ARM JSON templates or Bicep files used to define deployment stacks. To learn how to author an artifact as an ARM resource, see:
Azure Blueprints can be fully managed through Azure portal. As organizations advance in their use of
Azure Blueprints, they should start thinking of blueprint definitions as managed code. This concept
is often referred to as Infrastructure as Code (IaC). Treating your blueprint definitions as code
offers additional advantages beyond what Azure portal offers. These benefits include:
Sharing blueprint definitions
Backing up your blueprint definitions
Reusing blueprint definitions in different tenants or subscriptions
Placing the blueprint definitions in source control
Automated testing of blueprint definitions in test environments
Support of continuous integration and continuous deployment (CI/CD) pipelines
Whatever your reasons, managing your blueprint definitions as code has benefits. This article shows
how to use the Import-AzBlueprintWithArtifact and Export-AzBlueprintWithArtifact commands in the
Az.Blueprint module.
Prerequisites
This article assumes a moderate working knowledge of Azure Blueprints. If you haven't done so yet,
work through the following articles:
Creating and managing blueprint
definitions and assignments with PowerShell
If it isn't already installed, follow the instructions in
Add the Az.Blueprint module to install and
validate the Az.Blueprint module from the PowerShell Gallery.
Folder structure of a blueprint definition
Before looking at exporting and importing blueprints, let's look at how the files that make up the
blueprint definition are structured. A blueprint definition should be stored in its own folder.
Important
If no value is passed to the Name parameter of the Import-AzBlueprintWithArtifact cmdlet,
the name of the folder the blueprint definition is stored in is used.
Along with the blueprint definition, which must be named blueprint.json, are the artifacts that
the blueprint definition is composed of. Each artifact must be in the subfolder named artifacts.
Put together, the structure of your blueprint definition as JSON files in folders should look as
follows:
.
|
|- MyBlueprint/ _______________ # Root folder name becomes default name of blueprint definition
| |- blueprint.json __________ # The blueprint definition. Fixed name.
|
| |- artifacts/ ______________ # Subfolder for all blueprint artifacts. Fixed name.
| |- artifact.json ________ # Blueprint artifact as JSON file. Artifact named from file.
| |- ...
| |- more-artifacts.json
Export your blueprint definition
The steps to exporting your blueprint definition are straightforward. Exporting the blueprint
definition can be useful for sharing, backup, or placing into source control.
Blueprint [required]
Specifies the blueprint definition
Use Get-AzBlueprint to get the reference object
OutputPath [required]
Specifies the path to save the blueprint definition JSON files to
The output files are in a subfolder with the name of the blueprint definition
Version (optional)
Specifies the version to output if the Blueprint reference object contains references to
more than one version.
Get a reference to the blueprint definition to export from the subscription represented as
{subId}:
# Login first with Connect-AzAccount if not using Cloud Shell
# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'MyBlueprint' -Version '1.1'
Use the Export-AzBlueprintWithArtifact cmdlet to export the specified blueprint definition:
Once you have either an exported blueprint definition or have a
manually created blueprint definition in the
required folder structure, you can import that
blueprint definition to a different management group or subscription.
The management group ID to save the blueprint definition to if not the current context default
Either ManagementGroupId or SubscriptionId must be specified
SubscriptionId (optional)
The subscription ID to save the blueprint definition to if not the current context default
Either ManagementGroupId or SubscriptionId must be specified
Use the Import-AzBlueprintWithArtifact cmdlet to import the specified blueprint definition:
# Login first with Connect-AzAccount if not using Cloud Shell
Import-AzBlueprintWithArtifact -Name 'MyBlueprint' -ManagementGroupId 'DevMG' -InputPath 'C:\Blueprints\MyBlueprint'
As a Microsoft Azure solutions architect, you advise stakeholders and translate business requirements into designs for Azure solutions that align with the Azure Well-Architected Framework and Cloud Adoption Framework for Azure.