update-grub Command: Tutorial & Examples

Generate or update the GRUB bootloader configuration file

The update-grub command is an essential utility on Debian-based Linux systems that use the GRUB bootloader. It automates generating the GRUB configuration file, which defines the boot menu and controls how the system starts. This article explains how update-grub works, its importance, usage examples, common parameters, troubleshooting tips, and advanced topics for system administrators working in command-line environments.

What update-grub Does

The update-grub command scans the system for installed operating systems, available Linux kernels, and other bootable partitions, then generates a new GRUB configuration file—commonly located at /boot/grub/grub.cfg. This file instructs GRUB what boot options to display and how to boot the selected system.

On Debian-based distributions, update-grub is typically a wrapper script around the underlying command grub-mkconfig. It collects information from various configuration files and scripts to dynamically build the boot menu without manual editing.

Why update-grub Is Important

The bootloader is the first software that runs when a computer starts, responsible for loading the operating system kernel. If the GRUB configuration is outdated, missing entries, or incorrect, the system might fail to boot or not present new kernels or operating systems in the boot menu.

Running update-grub ensures the boot menu reflects the current system state. For example, after installing a new kernel or another OS in a dual-boot setup, update-grub must be run to detect and include these entries in the boot menu.

How update-grub Works

When you execute update-grub, it performs these steps:

Reads main GRUB configuration variables from /etc/default/grub.
Scans the /boot directory for Linux kernel images (vmlinuz-*) and initial RAM disks (initrd.img-*).
Executes scripts in the /etc/grub.d/ directory to detect operating systems, kernels, and other bootable entries.
Probes other partitions to detect non-Linux OSes such as Windows or BSD.
Combines all gathered information and templates to generate the final GRUB configuration file, typically /boot/grub/grub.cfg.

This automated process eliminates the need to manually edit complex GRUB configuration files and adapts the boot menu dynamically to system changes.

Technical Background

GRUB (GRand Unified Bootloader) is a flexible bootloader widely used in Linux systems. It uses a configuration file (grub.cfg) that defines the boot menu, default boot entry, timeout, kernel parameters, and other options.

The grub.cfg file is not meant to be edited manually because it is automatically generated by tools like update-grub or grub-mkconfig. Instead, administrators adjust settings in /etc/default/grub and scripts in /etc/grub.d/, then run update-grub to regenerate grub.cfg.

At boot time, GRUB reads grub.cfg to display the boot menu and execute the selected boot commands, loading the kernel and initial RAM disk.

Command History and Evolution

update-grub originated as a Debian convenience script to simplify interacting with the more complex grub-mkconfig command. Over time, it became standard on Debian and Ubuntu systems for regenerating GRUB configs after system changes.

Other distributions like Arch Linux do not provide update-grub but expect administrators to run grub-mkconfig manually. The core functionality remains the same: scan the system and generate grub.cfg.

How to Use update-grub

On Debian-based systems, run update-grub with superuser privileges since it writes to /boot:

sudo update-grub

Sample output:

Generating grub configuration file ...
Found linux image: /boot/vmlinuz-6.0.0-1-amd64
Found initrd image: /boot/initrd.img-6.0.0-1-amd64
Found linux image: /boot/vmlinuz-5.10.0-8-amd64
Found initrd image: /boot/initrd.img-5.10.0-8-amd64
Found Windows 10 on /dev/sda1
done

This output shows detected Linux kernel and initrd images, as well as other installed operating systems.

Common Command Line Parameters

update-grub usually passes options to grub-mkconfig. Common parameters include:

-o [file]
Specify the output file for the generated GRUB configuration. The default is /boot/grub/grub.cfg.
```
sudo update-grub -o /boot/grub/grub-custom.cfg
```
This can be useful for testing alternative configurations without overwriting the default.
--help
Display help information about the command.

Note that on some distributions, update-grub is not available. Instead, use:

sudo grub-mkconfig -o /boot/grub/grub.cfg

Customization and Configuration

Before running update-grub, you can customize the behavior of the GRUB menu by editing:

/etc/default/grub:
This file contains variables controlling GRUB options like GRUB_TIMEOUT (boot menu timeout), GRUB_DEFAULT (default boot entry), GRUB_CMDLINE_LINUX ( kernel parameters), and more.
/etc/grub.d/:
This directory contains executable scripts that define what entries appear in the boot menu. For example, 10_linux detects Linux kernels, 30_os-prober detects other OSes.

After modifying these files or scripts, you must run update-grub to regenerate the boot menu.

Potential Problems and Pitfalls

Permission Denied: Running update-grub without root privileges will fail to write the config file.
Missing or Corrupted Scripts: If /etc/grub.d/ or its scripts are missing or broken, the generated menu may be incomplete.
Misconfigured /etc/default/grub: Invalid syntax or incorrect variables can cause boot menu issues.
Disk Space: A full /boot partition will prevent writing grub.cfg.
Multiple Bootloaders: On multi-boot systems with several bootloaders, overwriting configs may cause conflicts.
Not Available Command: Some distros lack update-grub and require manual use of grub-mkconfig.

Common Errors and Troubleshooting

If update-grub fails or the boot menu is incorrect:

Check permissions with:
```
ls -l /boot/grub/grub.cfg
```
Verify space on /boot:
```
df -h /boot
```
Inspect /etc/default/grub for syntax errors:
```
sudo nano /etc/default/grub
```
Review scripts in /etc/grub.d/ for executable permissions:
```
ls -l /etc/grub.d/
```
Run update-grub with increased verbosity by executing grub-mkconfig directly:
```
sudo grub-mkconfig -o /boot/grub/grub.cfg -v
```
Check system logs for errors related to GRUB or disk issues.

Practical Examples Using update-grub

Example 1: Update GRUB After Kernel Installation

After installing a new kernel package, run:

sudo update-grub

Expected output:

Generating grub configuration file ...
Found linux image: /boot/vmlinuz-6.0.0-1-amd64
Found initrd image: /boot/initrd.img-6.0.0-1-amd64
Found linux image: /boot/vmlinuz-5.10.0-8-amd64
Found initrd image: /boot/initrd.img-5.10.0-8-amd64
done

This refreshes the boot menu to include the new kernel.

Example 2: Generate GRUB Config to Custom File

To create a GRUB configuration file at a different location:

sudo update-grub -o /boot/grub/grub-custom.cfg

This is useful for testing or managing multiple configurations.

Example 3: Using update-grub on Non-Debian Systems

On distributions like Arch Linux, run:

sudo grub-mkconfig -o /boot/grub/grub.cfg

as update-grub might not exist.

Example 4: Change Default Boot Entry

Edit /etc/default/grub:

GRUB_DEFAULT=2
GRUB_TIMEOUT=5

Then update GRUB:

sudo update-grub

This sets the third menu entry as the default and reduces the boot menu timeout to 5 seconds.

Scripting and Automation

For automated environments, you can include update-grub in scripts to keep boot menus updated after kernel or OS changes. Example bash snippet:

#!/bin/bash
echo "Updating GRUB configuration..."
sudo update-grub
echo "GRUB update complete."

You can schedule this in cron or as part of post-install hooks.

Performance and Security Considerations

Running update-grub requires root privileges, so limit access to trusted users only.
Avoid running update-grub unnecessarily to reduce system load and disk writes.
Ensure /boot has sufficient free space to prevent failures.
Backup existing /boot/grub/grub.cfg before major changes.

Possible Alternatives or Related Commands

grub-mkconfig: The underlying command that update-grub wraps.
grub-install: Installs GRUB to a disk or partition but does not update configs.
On non-Debian systems, manual use of grub-mkconfig is required.
Other bootloaders like LILO or systemd-boot serve similar purposes but require different tools.

Edge Cases and Lesser-Known Features

You can add custom boot entries by creating executable scripts in /etc/grub.d/40_custom.
Chainloading other bootloaders or OSes is supported via configuration scripts.
Use os-prober to detect additional operating systems if it is disabled or missing.
Customize GRUB themes or backgrounds by editing /etc/default/grub and related files.

Tips and Best Practices

Always back up /boot/grub/grub.cfg before running update-grub if you have custom changes.
After kernel upgrades or OS installs, run update-grub promptly.
Use /etc/default/grub to control timeout, default entry, and kernel command line options.
Test custom configurations by generating to alternate files before overwriting the default.
For debugging, inspect logs and run grub-mkconfig with verbose flags.

Cheatsheet

sudo update-grub
sudo update-grub -o /path/to/custom.cfg
sudo grub-mkconfig -o /boot/grub/grub.cfg  # Alternative to update-grub
sudo grub-install /dev/sda                  # Install GRUB to disk MBR/EFI
sudo nano /etc/default/grub                  # Edit GRUB variables
ls -l /etc/grub.d/                           # View boot menu scripts