How to Install Azure Linux on Azure Virtual Machines

Azure Linux is Microsoft’s own Linux distribution built for cloud workloads, containers, and Azure services. It is lightweight, open source, and designed to run efficiently on Microsoft’s cloud infrastructure. Many users knew it earlier as CBL-Mariner, but Microsoft now uses the Azure Linux name across cloud and container-focused use cases.

If you want to test Azure Linux on an Azure Virtual Machine, you have three practical options. The easiest method is to create a VM from an available Azure Linux image in the Azure Portal. If the image does not appear in your region or subscription, you can use Azure CLI to find and deploy it. Advanced users can also build or upload a custom Azure Linux image for full control over the operating system.

This guide covers all three methods step by step.

What Is Azure Linux?

Azure Linux is a Microsoft-maintained Linux distribution created specifically for Azure workloads. Microsoft uses it for container-based workloads and Azure Kubernetes Service. The distribution focuses on a reduced package footprint, automated security updates, and consistent performance characteristics from the host all the way up to the container.

Azure Linux is not a traditional desktop Linux distribution like Ubuntu, Fedora, or Linux Mint. It is built for cloud, server, container, and enterprise workloads.

You may want to use Azure Linux on a VM if you are:

• Testing Microsoft’s Linux distribution
• Building container workloads
• Creating a lightweight Linux server
• Preparing an Azure-native development environment
• Learning how Microsoft Linux images work in Azure
• Creating a base image for internal workloads

Before You Start

Before creating an Azure Linux VM, make sure your Azure account is active and properly configured. If you run into trouble signing in, check Can’t Sign In to Microsoft Azure Account? 7 Fixes That Work before continuing.

If you use an Azure free account and see unexpected access issues, review the Unable to Access Azure Free Account guide for eligibility and fix steps.

You need the following before you start:

• An active Azure subscription
• Permission to create virtual machines in your subscription
• A resource group (existing or new)
• Basic knowledge of SSH key authentication
• Azure Portal access or Azure CLI installed on your machine
• An SSH key pair for secure login

Some Marketplace images also require you to accept image terms before deployment. Azure CLI includes the az vm image accept-terms command for this situation.

Method 1: Install Azure Linux VM Using Azure Portal

The Azure Portal method is the easiest option for most users. You create and configure the VM entirely from the browser.

Step 1: Open Azure Virtual Machines

Sign in to the Azure Portal. Use the search bar at the top and navigate to:

Virtual machines > Create > Azure virtual machine

Step 2: Configure Basic VM Details

In the Basics tab, fill in the required details.

For a test VM, a small B-series size is enough. Before selecting a size, check Azure VM Series Retirement 2028: Affected VMs and Migration to avoid deploying on VM families that are scheduled for retirement.

Step 3: Choose the Azure Linux Image

In the Image field, search for:

Azure Linux

Select the Azure Linux image from the list if it appears in your region and subscription.

If Azure Linux does not show in the image list, do not assume it is unavailable everywhere. Image availability can vary by region, offer, SKU, and subscription type. Use the Azure CLI method described in the next section to search for the correct image.

Step 4: Set Administrator Account

SSH key authentication is safer than password login for Linux VMs. In the Administrator account section, select SSH public key.

If Azure generates a private key for you, download and store it securely. You need this key to connect to your VM.

Step 5: Configure Inbound Ports

In the inbound port settings, allow SSH so you can connect to the VM after deployment.

Allow selected ports: SSH 22

For production environments, restrict SSH access to your own IP address from the Networking tab or by editing the Network Security Group after deployment. Avoid leaving port 22 open to all IP addresses.

If you plan to install a web server later, you can also allow:

HTTP 80
HTTPS 443

Only open ports you actually need.

Step 6: Configure Disk and Networking

For testing, the default OS disk settings work fine. Use Standard SSD or Premium SSD depending on your workload. If you later encounter a disk missing after resizing, the How to Fix an Azure VM Data Disk Missing After Resize guide covers common disk recovery steps.

Azure automatically creates the virtual network, subnet, public IP address, network interface, and Network Security Group with default settings. For a test VM, these defaults are sufficient.

Step 7: Review and Create the VM

After filling in all required details, click:

Review + create

Azure validates the configuration. If everything passes, click:

Create

Wait for deployment to complete. Once the VM is ready, open the VM resource page and copy the public IP address.

Method 2: Install Azure Linux VM Using Azure CLI

The Azure CLI method is useful when the Azure Linux image does not appear clearly in the Portal, or when you want a repeatable deployment process. If Azure CLI fails with a DLL error on Windows, see Azure CLI DLL Load Failed While Importing win32file before continuing.

Step 1: Sign In to Azure CLI

Open Windows Terminal, PowerShell, Command Prompt, or Azure Cloud Shell.

Run:

az login

Complete the browser sign-in process.

Step 2: Create a Resource Group

Create a resource group to keep your VM and related resources organized:

az group create \
  --name azurelinux-rg \
  --location eastus

Replace eastus with your preferred Azure region.

Step 3: Search for Azure Linux Images

Azure VM images use a URN format:

Publisher:Offer:Sku:Version

Search available Azure Linux images with this command:

az vm image list \
  --all \
  --output table | grep -i "azurelinux"

On Windows PowerShell, use:

az vm image list --all --output table | Select-String "azurelinux"

You can also search by publisher:

az vm image list \
  --all \
  --publisher Microsoft \
  --output table

Always confirm the current publisher, offer, SKU, and version from Azure CLI before deploying. Image names and availability change over time.

Step 4: Create the Azure Linux VM

Once you find the correct image URN, use it in the az vm create command:

az vm create \
  --resource-group azurelinux-rg \
  --name azurelinux-vm \
  --image "actual-publisher:actual-offer:actual-sku:latest" \
  --admin-username azureuser \
  --generate-ssh-keys \
  --size Standard_B2s

Replace actual-publisher:actual-offer:actual-sku:latest with the real image URN from the previous step.

Step 5: Open SSH Port

If SSH is not already open, allow port 22:

az vm open-port \
  --resource-group azurelinux-rg \
  --name azurelinux-vm \
  --port 22

For production environments, avoid opening SSH to all IP addresses. Create a more restrictive Network Security Group rule instead.

Step 6: Connect to the VM

After creation, Azure CLI shows the public IP address in the output.

Connect using:

ssh azureuser@YOUR-PUBLIC-IP

If you used a specific private key file, add the -i flag:

ssh -i ./azurelinux-key.pem azureuser@YOUR-PUBLIC-IP

Method 3: Install Azure Linux Using a Custom Image

If you cannot find a ready Azure Linux image, or you need full control over the operating system, you can create a custom Azure Linux image. This method suits developers, DevOps teams, and organizations that need a customized base image with specific packages, security baselines, or preinstalled agents.

A typical custom image workflow looks like this:

1. Download or build the Azure Linux image
2. Install Azure Linux locally in Hyper-V, QEMU, or another hypervisor
3. Configure required packages and settings
4. Prepare the VM disk
5. Convert the disk to a supported VHD format
6. Upload the VHD to Azure
7. Create a managed image or Azure Compute Gallery image
8. Deploy a VM from that image

This method is not recommended for beginners. Use it only when a ready Marketplace image does not meet your requirements.

Basic Commands After Connecting to Azure Linux

After you connect to your Azure Linux VM over SSH, run these commands to verify the installation and get started.

Check the OS details:

cat /etc/os-release

Check the kernel version:

uname -r

Update installed packages:

sudo tdnf update -y

Azure Linux uses tdnf, a lightweight package manager built for the CBL-Mariner and Azure Linux ecosystem.

Install basic tools:

sudo tdnf install -y curl wget vim tar

Check disk usage:

df -h

Check memory:

free -h

Check IP addresses:

ip addr

How to Install a Web Server on Azure Linux

You can use your Azure Linux VM as a basic web server by installing Nginx from the default repositories.

Install Nginx:

sudo tdnf install -y nginx

Start Nginx:

sudo systemctl start nginx

Enable it to start on boot:

sudo systemctl enable nginx

Check the service status:

sudo systemctl status nginx

If your Network Security Group allows port 80, open the VM public IP in a browser:

http://YOUR-VM-PUBLIC-IP

If the page does not load, verify that port 80 is open in the VM’s Network Security Group rules.

Common Problems and Fixes

Azure Linux Image Not Showing in Azure Portal

Image availability varies by region, subscription, offer, and SKU.

Try these fixes:

• Search for Azure Linux in the Marketplace search bar
• Switch to a different Azure region
• Use Azure CLI to list available images as described in Method 2
• Verify your subscription has permission to deploy Marketplace images
• Use a custom image if no ready image is available

CLI Says Marketplace Terms Must Be Accepted

Some images require you to accept Marketplace terms before deployment. Use the az vm image accept-terms command:

az vm image accept-terms \
  --urn publisher:offer:sku:version

Replace the URN with the actual image URN from your search results.

SSH Connection Not Working

If SSH fails after deployment, check these settings:

• VM is in a running state
• A public IP address is assigned
• Port 22 is allowed in the Network Security Group
• You are using the correct username (azureuser by default)
• You are using the correct SSH private key file
• Your local network does not block outbound SSH on port 22

If you still cannot connect, use Azure’s built-in serial console or Run Command feature from the Azure Portal to access the VM without SSH. If you lose root access entirely, see How to Reset Root Password on a Linux VM in Azure for recovery methods.

For Azure Entra ID authentication issues on Windows-based VMs, see How to Fix RDP to Azure Server Using Entra ID for context on identity-related access problems.

Package Install Command Fails

If tdnf install returns errors, update the package database first:

sudo tdnf update -y

Then retry the install:

sudo tdnf install -y package-name

If the package is not available, it may not exist in the default Azure Linux repositories. In that case, you need to add a third-party repository or build the package manually.

Azure Sign-In or Subscription Access Issues

If you see authentication errors in Azure CLI or the Portal, check Can’t Sign In to Microsoft Azure Account? 7 Fixes That Work for known causes and fixes. If your tenant has expired, How to Recover an Expired Azure or Microsoft 365 Tenant explains the recovery process before Microsoft permanently deletes the tenant.

For AADSTS authentication errors that block sign-in silently, see How to Fix AADSTS50058 Error in Azure for the session and cookie-related causes.

Azure Linux vs Ubuntu on Azure VM

Azure Linux and Ubuntu both work on Azure VMs, but they serve different needs.

If you are new to Linux, Ubuntu is easier to start with due to its larger community documentation. If your goal is to test Microsoft’s Linux stack or build Azure-native workloads, Azure Linux is worth using. For teams planning to migrate retiring Azure Virtual Machines to latest-generation VMs, Azure Linux is also a strong candidate as a fresh base image.

FAQs

Related Guides

• How to Reset Root Password on a Linux VM in Azure (4 Methods That Work)
• How to Fix an Azure VM Data Disk Missing After Resize
• How to Migrate Retiring Azure Virtual Machines to Latest-Generation VMs