Edit the GRUB Environment Block with grub-editenv

One wrong variable in the GRUB environment block can boot the wrong entry, so practise grub-editenv on a throwaway file first. This guide covers inspecting, setting and removing variables safely. The examples use grub-editenv from grub-common 2.12-1ubuntu7.3, installed here as GRUB 2.12-1ubuntu7.3.

Allow about ten minutes. You need a shell and the GRUB utilities package. Reading a block is usually unprivileged; editing the system block at /boot/grub/grubenv normally needs sudo. This tool changes persistent GRUB state, so do not experiment on the real file until the temporary example behaves as expected.

1. Check the installed command

Confirm which executable will run and record its version. These are ordinary, read-only commands:

$ command -v grub-editenv
/usr/bin/grub-editenv
$ grub-editenv --version
grub-editenv (GRUB) 2.12-1ubuntu7.3

The exact package revision can differ after updates. If your version is different, check its own help before copying an option into automation.

Checkpoint: you have confirmed the binary and know whether you are working with a temporary file or the live boot block.

2. Practise on a temporary block

Use a new file under /tmp so the first write cannot alter the boot loader's environment. The shell creates a unique name; keep it in the same shell for the following steps:

test_file=$(mktemp /tmp/grubenv.XXXXXX)
grub-editenv "$test_file" create
grub-editenv "$test_file" list

3. Set and verify variables

Set one or more variables with NAME=VALUE arguments. This example uses names that are easy to recognise and does not control your machine's boot menu:

$ grub-editenv "$test_file" set demo_mode=1 example_label=check
$ grub-editenv "$test_file" list
demo_mode=1
example_label=check

set adds a missing variable and replaces the value of an existing one. Pass each assignment as its own shell argument, and quote one when its value contains whitespace or shell metacharacters, for example 'note=maintenance window'. Do not paste untrusted text into a shell command without reviewing its quoting first.

Use the following check immediately after a change:

grub-editenv "$test_file" list
printf 'grub-editenv status: %s\n' "$?"

On the tested system, the list contains the two assignments and the status is 0. The status belongs to list, so do not run another command before printing it.

4. Remove one variable

There is no separate edit screen. Remove named variables with unset, then list the block again:

$ grub-editenv "$test_file" unset example_label
$ grub-editenv "$test_file" list
demo_mode=1

This is the normal undo for an individual variable. If you need the old value, recover it from a backup or set it again with the exact previous assignment. Keep the test file until you have finished checking your command, then leave it in /tmp for normal temporary-file cleanup by the system.

5. Inspect the live environment block

The manpage uses a hyphen as a special filename: - means the default /boot/grub/grubenv. Inspect it before making any change:

$ grub-editenv - list
saved_entry=...

The output is host-specific and an empty result is possible. If the default path is not appropriate for your installation, pass the actual environment-block filename explicitly instead of assuming the conventional path. A successful listing is also not proof that every GRUB configuration can use the block: GRUB's environment storage has platform and filesystem constraints, and other GRUB tools may manage particular variables. The command only reports what is stored in the block.

Checkpoint: you have recorded the current output and confirmed the target path. If you cannot explain which file will be changed, stop here.

6. Back up before editing persistent state

Before changing the live block, make a backup with a distinct destination. This is a state-changing operation and needs elevated privileges:

$ sudo cp --preserve=all /boot/grub/grubenv /boot/grub/grubenv.before-grub-editenv
$ sudo grub-editenv /boot/grub/grubenv list

Choose a backup destination that does not already contain a copy you might confuse with this one, and confirm the backup command succeeded before continuing. If the source path does not exist, do not create a blank file at the default location without first understanding how GRUB was installed.

To recover the saved state, stop any boot configuration work and restore the backup explicitly:

$ sudo cp --preserve=all /boot/grub/grubenv.before-grub-editenv /boot/grub/grubenv
$ sudo grub-editenv /boot/grub/grubenv list

Recovery: restoration replaces the whole block. Treat it as a recovery action, not as a way to merge later changes.

7. Make and verify one live change

Only after the backup and inspection should you set a variable that another GRUB feature or administrator has explicitly asked you to change. Replace the placeholder with the exact assignment you have reviewed:

$ sudo grub-editenv /boot/grub/grubenv set VARIABLE_NAME=REVIEWED_VALUE
$ sudo grub-editenv /boot/grub/grubenv list

The second command should show the reviewed value. If it does not, do not reboot to see whether it works: check the path, permissions and variable spelling, then restore the backup if the block no longer represents the intended state.

To remove one known variable later, use the same explicit path:

$ sudo grub-editenv /boot/grub/grubenv unset VARIABLE_NAME
$ sudo grub-editenv /boot/grub/grubenv list

Warning: there is no delete command for the entire block. The manpage documents removing the whole environment block with rm /boot/grub/grubenv; that is destructive and can break consumers that expect the block, so do not use it as routine cleanup. Restore the backup or remove only named variables instead.

Done means