Skip to main content
Package lists define which RPM packages are installed in your Azure Linux image. They are JSON files referenced from the image configuration’s PackageLists array.

​
Package List Format

Package lists are simple JSON files with a packages array:
packagelist.json
{
    "packages": [
        "package-name-1",
        "package-name-2",
        "package-name-3"
    ]
}

​
Referencing Package Lists

Package lists are referenced in the SystemConfigs section: 
"SystemConfigs": [
    {
        "PackageLists": [
            "packagelists/core-packages-image.json",
            "packagelists/hyperv-packages.json",
            "packagelists/cloud-init-packages.json"
        ]
    }
]
Paths are relative to the image configuration file location.

​
Package List Processing

Package lists are processed in linear order:
  1. Each file is scanned sequentially
  2. All packages are combined via union operation
  3. Dependencies are resolved automatically
  4. Final package list is installed
It is recommended that initramfs is the last package in your lists to speed up installation.

​
Kernel Packages

Do not include kernel packages in PackageLists!
  • Use KernelOptions instead
  • Including kernel in PackageLists results in undefined behavior
  • If packages depend on a kernel, specify it in KernelOptions

​
Correct Kernel Configuration

{
    "SystemConfigs": [
        {
            "PackageLists": [
                "packagelists/core-packages-image.json"
            ],
            "KernelOptions": {
                "default": "kernel"
            }
        }
    ]
}

​
Built-in Package Lists

Azure Linux provides several standard package lists:

​
Core Package Lists

​
core-packages-image.json
Essential packages for bootable images:
  • shim - Secure boot loader
  • grub2-efi-binary - GRUB bootloader
  • ca-certificates - SSL certificates
  • initramfs - Initial RAM filesystem
  • dracut-hostonly - Initramfs generator
  • shadow-utils - User/group utilities
core-packages-image.json
{
    "packages": [
        "shim",
        "grub2-efi-binary",
        "ca-certificates",
        "cronie-anacron",
        "logrotate",
        "core-packages-base-image",
        "dracut-hostonly",
        "dracut-vrf",
        "initramfs",
        "shadow-utils"
    ]
}
​
core-packages-container.json
Minimal packages for container images (no boot components)
​
core-packages-image-aarch64.json
Core packages optimized for ARM64 architecture

​
Virtualization Packages

​
hyperv-packages.json
Hyper-V integration services
hyperv-packages.json
{
    "packages": [
        "dracut-hyperv",
        "hyperv-daemons"
    ]
}
​
qemu-guest-packages.json
QEMU/KVM guest agent and tools
​
virt-guest-packages.json
Generic virtualization guest packages
​
virtualization-host-packages.json
Packages for running VMs (libvirt, qemu, etc.)

​
Cloud and Deployment

​
cloud-init-packages.json
Cloud-init for cloud environment initialization
​
azurevm-packages.json
Azure-specific VM packages (WALinuxAgent, etc.)
​
marketplace-tools-packages.json
Azure Marketplace image tools

​
Security Packages

​
selinux.json
Basic SELinux packages
​
selinux-full.json
Complete SELinux packages with all policies
​
fips-packages.json
FIPS 140-2 compliant cryptographic modules
​
cvm-packages.json
Confidential VM packages (attestation, etc.)
​
drtm.json
Dynamic Root of Trust Measurement packages

​
Development and Tools

​
developer-packages.json
Development tools (gcc, make, git, etc.)
​
core-tools-packages.json
Additional system utilities and tools

​
Specialized Images

​
minimal-os-packages.json
Minimal bootable OS (smallest footprint)
​
distroless-packages-container.json
Distroless container base packages
​
distroless-packages-container-minimal.json
Ultra-minimal distroless packages
​
distroless-packages-debug.json
Distroless with debugging tools
​
baremetal-packages.json
Bare metal hardware support
​
rt-packages.json
Real-time kernel packages

​
Utilities

​
ssh-server.json
OpenSSH server packages
​
grub2-mkconfig.json
GRUB2 mkconfig support packages
​
core-container-builder-packages.json
Container build tools (Docker, buildah, etc.)

​
Creating Custom Package Lists

Create your own package list for specific use cases:

​
Example: Web Server Package List

packagelists/web-server.json
{
    "packages": [
        "nginx",
        "php",
        "php-fpm",
        "mariadb",
        "certbot"
    ]
}

​
Example: Monitoring Package List

packagelists/monitoring.json
{
    "packages": [
        "prometheus",
        "grafana",
        "node_exporter",
        "telegraf"
    ]
}

​
Using Custom Package Lists

"PackageLists": [
    "packagelists/core-packages-image.json",
    "packagelists/cloud-init-packages.json",
    "packagelists/web-server.json",
    "packagelists/monitoring.json"
]

​
Common Package Combinations

​
Virtual Machine Image

"PackageLists": [
    "packagelists/core-packages-image.json",
    "packagelists/hyperv-packages.json",
    "packagelists/cloud-init-packages.json",
    "packagelists/virt-guest-packages.json"
]

​
Azure Marketplace Image

"PackageLists": [
    "packagelists/core-packages-image.json",
    "packagelists/marketplace-tools-packages.json",
    "packagelists/azurevm-packages.json",
    "packagelists/hyperv-packages.json"
]

​
Minimal Container Base

"PackageLists": [
    "packagelists/core-packages-container.json"
]

​
FIPS-Compliant Image

"PackageLists": [
    "packagelists/core-packages-image.json",
    "packagelists/fips-packages.json",
    "packagelists/selinux.json"
]

​
Developer Workstation

"PackageLists": [
    "packagelists/core-packages-image.json",
    "packagelists/developer-packages.json",
    "packagelists/core-tools-packages.json",
    "packagelists/ssh-server.json"
]

​
Package Dependencies

Azure Linux automatically resolves package dependencies:
  • Dependencies are pulled from configured repositories
  • Transitive dependencies are included
  • Conflicts are detected and reported
  • Version requirements are satisfied
You only need to list direct packages - dependencies are handled automatically.

​
Package Repositories

Packages are installed from repositories defined in:
  1. Default Azure Linux repositories
  2. Custom repositories (for ISO installers via PackageRepos)

​
Using Custom Repositories

"PackageRepos": [
    {
        "Name": "CustomRepo",
        "BaseUrl": "https://myrepo.com/packages/$releasever/$basearch",
        "Install": true
    }
]
Then reference packages from that repository in your package lists:
packagelists/custom-packages.json
{
    "packages": [
        "my-custom-package",
        "another-custom-tool"
    ]
}

​
Best Practices

Order Package Lists Strategically

  • Place core/essential packages first
  • Add feature-specific packages next
  • Put initramfs last for faster installation

Keep Lists Modular

  • Create separate lists for different features
  • Reuse lists across configurations
  • Easier to maintain and understand

Document Package Purposes

  • Add comments in configuration files
  • Document why specific packages are included
  • Note dependencies between packages

Test Package Combinations

  • Verify packages work together
  • Check for size constraints
  • Test functionality after installation

Never Include Kernel in Lists

  • Always use KernelOptions for kernels
  • Check dependencies don’t pull in kernels
  • Validate configuration before building

​
Troubleshooting

​
Package Not Found

If a package is not found during installation:
  1. Verify package name is correct
  2. Check package exists in repository
  3. Ensure repository is accessible
  4. Check repository architecture matches

​
Dependency Conflicts

If dependency conflicts occur:
  1. Review package versions
  2. Check for incompatible packages
  3. Verify repository priorities
  4. Consider alternative packages

​
Large Image Size

If your image is too large:
  1. Remove unnecessary package lists
  2. Use DisableRpmDocs option
  3. Set OverrideRpmLocales to NONE
  4. Audit packages for alternatives

​
Example Configurations

​
Minimal VM

{
    "SystemConfigs": [
        {
            "PackageLists": [
                "packagelists/minimal-os-packages.json"
            ],
            "KernelOptions": {
                "default": "kernel"
            },
            "DisableRpmDocs": true,
            "OverrideRpmLocales": "NONE"
        }
    ]
}

{
    "SystemConfigs": [
        {
            "PackageLists": [
                "packagelists/core-packages-image.json",
                "packagelists/hyperv-packages.json",
                "packagelists/cloud-init-packages.json",
                "packagelists/developer-packages.json",
                "packagelists/core-tools-packages.json"
            ],
            "KernelOptions": {
                "default": "kernel"
            }
        }
    ]
}

​
Next Steps

System Configuration

Configure system settings and options

Examples

View complete configuration examples

Build docs developers (and LLMs) love

Get started for freeTalk to us