Control image mode updates with download-only via bootc

The bootc utility has changed the way we think about system updates in image mode for Red Hat Enterprise Linux (RHEL). By treating the entire operating system as a container image, we gain atomicity, easy rollbacks, and a simplified deployment model. However, as many system administrators know, atomic doesn't always mean at the right time. Until recently, running a bootc upgrade would download and stage an update that would automatically apply on the next reboot—regardless of why that reboot occurred. 

For production environments with strict maintenance windows, this auto-apply behavior could lead to unintended changes during routine hardware checks or emergency restarts. To address this, we are introducing download-only mode. This feature gives administrators explicit control over when a staged update is allowed to become the active boot environment.

What is download-only mode?

This workflow is essential for organizations that require update validation before application, or for operations teams managing fleet-wide rollouts where network-intensive downloads and system-altering reboots must happen at different times. The download-only mode separates the update process into three distinct phases:

1. Download and stage: Pulling and preparing the new system image on disk.
2. Lock: Instructing the system not to switch to the new image on the next reboot.
3. Explicit application: The administrator explicitly triggers the finalization when they are ready for the update to take effect.

Putting it into practice

The primary interface for this feature is the introduction of the --download-only and --from-downloaded flags within the bootc upgrade command.

Staging an update without applying

When you want to pre-load a security patch during business hours without risking an accidental update, you can run the following command:

# bootc upgrade --download-only

This command pulls the latest image and prepares the new deployment. However, it is important to note that the state of this staged image does not persist across reboots. If the system reboots for any reason before you explicitly apply the update, it will clear the staged deployment to prevent stale updates from lingering on disk.

Checking the status

To see if you have a download-only update, you can use the enhanced bootc status output (using the --verbose flag for full details) as follows:

# bootc status --verbose

[...]
Staged:
  Image: quay.io/example/rhel-guest:latest
  Version: 10.2.20260126
  download-only: yes

The download-only: yes line provides immediate visibility, confirming that the system will not automatically switch to this version on the next boot.

Applying the update

When your maintenance window arrives, you can unlock the staged deployment for automatic application on the next shutdown or reboot using the --from-downloaded flag:

# bootc upgrade --from-downloaded

This command specifically targets the downloaded image without attempting to fetch new updates. It sets the download-only status to false and readying the system to switch on the next reboot.

Applying the update immediately, the following command unlocks the staged deployment and immediately reboots into it.

# bootc upgrade --from-downloaded --apply

Why this matters for the enterprise

The introduction of download-only mode brings bootc to feature parity with rpm-ostree, which many users relied on for Fedora CoreOS and Fedora IoT. It enables several critical enterprise use cases:

• Pre-deployment testing: QA teams can download updates to a staging environment, inspect the contents, and run validation scripts before committing to the reboot.
• Compliance and change control: The separation of "download" from "apply" allows for distinct approval steps in automated CI/CD pipelines.
• Maintenance windows: Administrators can pre-download updates during the day and choose exactly when to apply them (e.g., 2 AM) to maximize uptime.

Behind the scenes: OSTree and Composefs

Under the hood, this feature leverages new public APIs in the OSTree backend. While Phase 1 (available in RHEL 10.2) focuses on the OSTree backend, the architecture is designed to be backend-agnostic.

It is worth noting that this feature is not yet implemented for the Composefs-native backend. If attempted on a system using the experimental Composefs backend, bootc will provide this clear error message: "This feature is not supported on composefs backend."

Final thoughts

Control is a prerequisite for stability. By introducing the download-only mode, bootc provides the flexibility needed to run image-based RHEL in the most demanding production environments. You can now separate the network-heavy task of fetching images from the mission-critical task of updating the system state.