The rEFInd Boot Manager:
Configuring the Boot Manager

by Roderick W. Smith,

Originally written: 3/14/2012; last Web page update: 3/20/2020, referencing rEFInd 0.12.0

This Web page is provided free of charge and with no annoying outside ads; however, I did take time to prepare it, and Web hosting does cost money. If you find this Web page useful, please consider making a small donation to help keep this site up and running. Thanks!

Donate $1.00 Donate $2.50 Donate $5.00 Donate $10.00 Donate $20.00 Donate another value

Beginning in March 2020 and until schools re-open in the United States, I'm donating all rEFind proceeds to No Kid Hungry, which aims to eliminate childhood hunger in the United States. I'll make donations early each month based on the previous month's donations to rEFInd.

This page is part of the documentation for the rEFInd boot manager. If a Web search has brought you here, you may want to start at the main page.

Many casual users will be able to use rEFInd without making changes to its settings; in its default configuration, the boot manager automatically detects all the EFI boot loader programs you have on your EFI System Partition (ESP) (or your macOS boot partition, in the case of Macs) in conventional locations and displays icons for them. On Macs, rEFInd also presents legacy BIOS boot options by default. Sometimes, though, you may want to tweak rEFInd's configuration. Sometimes you can obtain your desired results by adjusting the filenames of your boot loaders. Other times, you can edit rEFInd's configuration file, refind.conf, which resides in the same directory as its binary file (refind_x64.efi or whatever you've renamed it).

Broadly speaking, rEFInd's configuration file is broken down into two sections: global options and OS stanzas. The global options section sets options that apply globally—to set the timeout period, enable graphics or text mode, and so on. OS stanzas are optional, but if present, they enable you to add new boot options or replace the auto-detected options with customized ones. Both sections include configuration lines and comment lines, the latter being denoted by a leading hash mark (#). rEFInd ignores comment lines, so you can add explanatory text. The default configuration file includes numerous comments explaining each of the options.

Hiding and Displaying EFI Boot Loaders

A common complaint among rEFInd users is that rEFInd displays too many boot options. This problem is getting worse as OS vendors deliver more and more tools in the form of EFI programs installed on the ESP. It's difficult for me to keep up with this flood, and what one person considers a necessary program another may consider pointless clutter, making it hard to set useful defaults. Fortunately, rEFInd provides several ways to hide OSes—or to make them appear, if they don't by default. Methods to do this include:

Setting OS Icons

In addition to hiding boot loaders, you can adjust their icons. You can do this in any of seven ways for auto-detected boot loaders:

As a special case, rEFInd assigns icons to the Windows and macOS boot loaders based on their conventional locations, so they get suitable icons even if they don't follow these rules.

These icon files should be in Apple's ICNS format, Portable Network Graphics (PNG) format, bitmap image file (BMP) format, or Joint Photographic Experts Group (JPEG) format, depending on the filename extension. As a general rule, PNG and ICNS files work best for icons, because they both support transparency, which is highly desirable in rEFInd icons, especially when the icon is shown against a full-screen banner. ICNS is an Apple-specific format, whereas PNG is cross-platform. BMP and JPEG files may be used as icons, but rEFInd does not support transparency with these formats. rEFInd relies on the LodePNG and NanoJPEG libraries for PNG and JPEG support, respectively. These libraries have certain limitations; for instance, NanoJPEG, and therefore rEFInd, does not support progressive JPEGs. If you have problems with a specific icon or banner image, check the libraries' pages and re-save or convert the image into a more generic form, or even to a different format.

In addition to the main OS tag icon, you can set the badge icon for a volume by creating a file called .VolumeBadge.icns, .VolumeBadge.png, .VolumeBadge.bmp, .VolumeBadge.jpg, or .VolumeBadge.jpeg in the root directory of a partition. If present, it replaces the disk-type icons that are overlaid on the main OS icon. If you use this feature, the badge is applied to all the boot loaders read from the disk, not just those stored in the root directory or the Apple boot loader location. You could use this feature to set a custom badge for different specific disks or to help differentiate multiple macOS installations on one computer. If you don't want any badges, you can add the badges option to hideui in refind.conf. Alternatively, or to hide just certain types of badges, you can replace the four badge icons in the rEFInd icons subdirectory (vol_external.png, vol_internal.png, vol_optical.png, and vol_net.png) with a completely transparent badge. The transparent.png file in the rEFInd icons directory may be used for this purpose.

The default icon sizes are 128x128 pixels for OS icons, 48x48 pixels for the second-row tools, and 32x32 pixels for badges. (These figures are all doubled on displays wider than 1920 pixels.) You can change the sizes of the big OS icons and the small tool icons with the big_icon_size and small_icon_size tokens in refind.conf, as noted in Table 1. The size of the disk-type badges is 1/4 the size of OS icons.

Adjusting the Global Configuration

You can adjust many of rEFInd's options by editing its configuration file, which is called refind.conf. You must first find this file, though. It is located in the rEFInd directory. On a UEFI-based PC, this directory will be located on the EFI System Partition (ESP), which can be in any number of places:

As a further twist, on Macs rEFInd can exist on its own partition or on the main macOS partition, depending on the version of rEFInd you've installed and the options you passed to the installation script. rEFInd has installed to the ESP by default since version 0.8.4. rEFInd typically lives on the ESP in the EFI/refind directory, or sometimes in EFI/BOOT or elsewhere. Thus, the rEFInd configuration file might be /boot/efi/EFI/refind/refind.conf, /boot/EFI/BOOT/refind.conf, /Volumes/ESP/EFI/refind/refind.conf, S:\EFI\refind\refind.conf, or something else, depending on your OS and mount point.

You can use any text editor you like to edit refind.conf, but be sure it saves the file in plain ASCII text, not in a word processing format. (In theory, a UTF-16 encoding should also work, but this has been poorly tested.) Note that the EFI shell includes its own editor. If you need to make a change before you launch an OS, you can launch a shell, change to the rEFInd directory, and type edit refind.conf to edit the file. This EFI editor is quite primitive, but it gets the job done. After editing, you'll need to reboot or re-launch rEFInd, or hit the Esc key, for rEFInd to read the changed configuration file.

Global configuration file options consist of a name token followed by one or more parameters, as in:

timeout 20

This example's name token is timeout and its parameter is 20. The net effect of this line is to set the timeout period to 20 seconds—rEFInd will wait 20 seconds before launching the default boot loader. Some options can take multiple parameters. These may be separated by commas, spaces, or tabs. The global options are summarized in the Table 1.

Table 1: Global options in refind.conf
Token Possible parameters Explanation
timeout numeric value Sets the timeout period in seconds. If 0, the timeout is disabled—rEFInd waits indefinitely for user input. If -1, rEFInd will normally boot immediately to the default selection; however, if a shortcut key (for instance, W for Windows) is pressed, that system will boot instead. If any other key is pressed, the menu will show with no timeout.
shutdown_after_timeout none or one of true, on, 1, false, off, or 0 If set to false or one of its synonyms (the default), rEFInd boots the option set via default_selection when the timeout period is reached. When set to true or one of its synonyms, rEFInd attempts to shut down the computer when the timeout period is reached. Many EFIs lack software shutdown support. On them, setting this option to true will cause a reboot or a hang once the timeout value is reached!
use_nvram none or one of true, on, 1, false, off, or 0 If set to true, on, or 1 (the default), stores rEFInd-specific variables in NVRAM. If set to false, off, or 0, stores these variables in the vars subdirectory of rEFInd's home directory, if possible. (Read-only filesystems obviously make this option impossible.) Using NVRAM ties rEFInd's variables to a specific computer and increases wear on the NVRAM, whereas storing them on disk makes the variables move with rEFInd (which is potentially useful on an installation on a removable disk).
screensaver numeric value Sets the number of seconds of inactivity before the screen blanks to prevent burn-in. The display returns after most keypresses (unfortunately, not including modifiers such as Shift, Control, Alt, or Option). The default is 0, which disables this feature. Setting this token to -1 causes a blank display until the timeout value passes or you press a key.
hideui banner, label, singleuser, safemode, hwtest, arrows, hints, editor, badges, or all Removes the specified user interface features. banner removes the banner graphic or background image, label removes the text description of each tag and the countdown timer, singleuser removes the single-user option from the macOS sub-menu, safemode removes the option to boot to safe mode from the macOS sub-menu, hwtest removes the Macintosh hardware test option, arrows removes the arrows to the right or left of the OS tags when rEFInd finds too many OSes to display simultaneously, hints removes the brief description of what basic keypresses do, editor disables the options editor, badges removes the device-type badges from the OS tags, and all removes all of these features. You can specify multiple parameters with this option. The default is to set none of these values.
icons_dir directory name Specifies a directory in which custom icons may be found. This directory should contain files with the same names as the files in the standard icons directory. The directory name is specified relative to the directory in which the rEFInd binary resides. The standard icons directory is searched if an icon can't be found in the one specified by icons_dir, so you can use this location to redefine just some icons. Preferred icon file formats are PNG (*.png) and ICNS (*.icns), because both these formats support transparency. You can use BMP (*.bmp) and JPEG (*.jpg or *.jpeg), but rEFInd does not support transparency with these formats, which is highly desirable in icons. Note that if no icons directory is found (either icons or one specified by icons_dir), rEFInd switches to text-only mode, as if textonly had been specified.
banner filename Specifies a custom banner file to replace the rEFInd banner image. The file should be an ICNS, BMP, PNG, or JPEG image with a color depth of 24, 8, 4, or 1 bits. The file path is relative to the directory where the rEFInd binary is stored. Note that some image features, such as JPEG's progressive encoding scheme, are not supported. See the comments on LodePNG and NanoJPEG earlier, in Setting OS Icons.
banner_scale noscale or fillscreen Tells rEFInd whether to display banner images pixel-for-pixel (noscale) or to scale banner images to fill the screen (fillscreen). The former is the default.
big_icon_size numeric value (at least 32) Sets the size of big icons (those used for OSes on the first row). All icons are square, so only one value is specified. If icon files don't contain images of the specified size, the available images are scaled to this size. The disk-type badge size is set indirectly by this token; badges are 1/4 the size of big icons. The default value is 128 on most systems, or 256 when the screen is wider than 1920 pixels.
small_icon_size numeric value (at least 32) Sets the size of small icons (those used for tools on the second row). All icons are square, so only one value is specified. If icon files don't contain images of the specified size, the available images are scaled to this size. The default value is 48 on most systems, or 96 when the screen is wider than 1920 pixels.
selection_big filename Specifies a graphics file that can be used to highlight the OS selection icons. This should be a 144x144 image in BMP, PNG, ICNS, or JPEG format, stored in rEFInd's main directory. (Images larger or smaller than 144x144 will be scaled, but the results may be ugly.)
selection_small filename Like selection_big, this sets an alternate highlight graphic, but for the smaller utility tags on the second row. This should be a 64x64 image in BMP, PNG, ICNS, or JPEG format, stored in rEFInd's main directory. (Images larger or smaller than 64x64 will be scaled, but the results may be ugly.)
showtools shell, memtest, gdisk, gptsync, install, apple_recovery, csr_rotate, mok_tool, fwupdate, netboot, about, hidden_tags, exit, shutdown, reboot, and firmware Specifies which tool tags to display on the second row. shell launches an EFI shell, memtest (or memtest86) launches the Memtest86 program, gdisk launches the partitioning tool of the same name, gptsync launches a tool that creates a hybrid MBR, install installs rEFInd from the booted medium to another ESP, apple_recovery boots the macOS Recovery HD, csr_rotate rotates through System Integrity Protection (SIP) values specified by csr_values, windows_recovery boots a Windows recovery tool, mok_tool launches a tool to manage Machine Owner Keys (MOKs) on systems with Secure Boot active, fwupdate launches a firmware-update tool, netboot launches the network boot tool (iPXE), about displays information about rEFInd, hidden_tags enables you to recover tags you've hidden exit terminates rEFInd, shutdown shuts down the computer (or reboots it, on some UEFI PCs), reboot reboots the computer, and firmware reboots the computer into the computer's own setup utility. The tags appear in the order in which you specify them. The default is shell, memtest, gdisk, apple_recovery, mok_tool, about, shutdown, reboot, firmware. Note that the shell, memtest, gdisk, apple_recovery, mok_tool, and fwupdate options all require the presence of programs not included with rEFInd. The gptsync option requires use of a like-named program which, although it ships with rEFInd, is not installed by default except under macOS. See the "Installing Additional Components" section of the Installing rEFInd page for pointers to the shell, Memtest86, gptsync, and gdisk programs. The apple_recovery option will appear only if you've got an Apple Recovery HD partition (which has a boot loader called The firmware option works only on computers that support this option; on other computers, the option is quietly ignored. See the Secure Boot page for information on Secure Boot and MOK management.
font font (PNG) filename You can change the font that rEFInd uses in graphics mode by specifying the font file with this token. The font file should exist in rEFInd's main directory and must be a PNG-format graphics file holding glyphs for all the characters between ASCII 32 (space) through 126 (tilde, ~), plus a glyph used for all characters outside of this range. See the Theming rEFInd page for more details.
textonly none or one of true, on, 1, false, off, or 0 rEFInd defaults to a graphical mode; however, if you prefer to do without the flashy graphics, you can run it in text mode by including this option (alone or with true, on, or 1). Passing false, off, or 0 causes graphics mode to be used. (This could be useful if you want to override a text-mode setting in an included secondary configuration file.) Text-only mode is implicitly set if rEFInd cannot find either a subdirectory called icons or a subdirectory named by icons_dir.
textmode text mode number Sets the text-mode video resolution to be used in conjunction with textonly or for the line editor and program-launch screens. This option takes a single-digit code. Mode 0 is guaranteed to be present and should be 80x25. Mode 1 is supposed to be either invalid or 80x50, but some systems use this number for something else. Higher values are system-specific. Mode 1024 is a rEFInd-specific code that means to not set any mode at all; rEFInd instead uses whatever mode was set when it launched. If you set this option to an invalid value, rEFInd pauses during startup to tell you of that fact. Note that setting textmode can sometimes force your graphics-mode resolution to a higher value than you specify in resolution. On Linux, the /sys/class/graphics/fb0/modes file holds available modes, but it may not be the same set of modes that EFI provides.
resolution one or two integer values Sets the video resolution used by rEFInd; takes either a width and a height or a single UEFI video mode number as options. For instance, resolution 1024 768 sets the resolution to 1024x768. On UEFI systems, resolution 1 sets video mode 1, the resolution of which varies from system to system. If you set a resolution that doesn't work on a UEFI-based system, rEFInd displays a message along with a list of valid modes. On a system built around EFI 1.x (such as a Mac), setting an incorrect resolution fails silently; you'll get the system's default resolution. You'll also get the system's default resolution if you set both resolution values to 0 or if you pass anything but one or two numbers. (Note that passing a resolution with an x, as in 1024x768, will be interpreted as one option and so will cause the default resolution to be used.) If you get a higher resolution than you request, try commenting out or changing the textmode value, since it can force the system to use a higher graphics resolution than you specify with resolution. Also, be aware that it is possible to set a valid resolution for your video card that's invalid for your monitor. If you do this, your monitor will go blank until you've booted an OS that resets the video mode.
enable_touch none or one of true, on, 1, false, off, or 0 Enables support for touch screens (as on tablets). Note that not all tablets provide the necessary support. If this feature is enabled and the tablet supports it, touching an OS or tool should launch it or enter a submenu. In a submenu, it is currently not possible to select a specific item; any touch will launch the default submenu option. This option is incompatible with enable_mouse. If both are specified, the one appearing later in refind.conf takes precedence. The default is off.
enable_mouse none or one of true, on, 1, false, off, or 0 Enables support for mice (and related pointing devices, such as trackballs). Note that not all EFIs provide the necessary support. If this feature is enabled and the computer supports it, clicking an OS or tool should launch it or enter a submenu. In a submenu, it is currently not possible to select a specific item; any click will launch the default submenu option. This option is incompatible with enable_touch. If both are specified, the one appearing later in refind.conf takes precedence. The default is off.
mouse_size numeric value Sets the size of the mouse pointer, in pixels squared. The default is 16.
mouse_speed numeric value Sets the speed of the mouse pointer, with higher numbers meaning faster tracking. The default is 1.
use_graphics_for osx, linux, elilo, grub, and windows Ordinarily, rEFInd clears the screen and displays basic boot information when launching any OS but macOS. For macOS, the default behavior is to clear the screen to the default background color and display no information. You can specify the simpler Mac-style behavior by specifying the OSes or boot loaders you want to work this way with this option. (OSes that should use text-mode displays should be omitted from this list.) Note that this option doesn't affect what the boot loader does; it may display graphics, text, or nothing at all. Thus, the effect of this option is likely to last for just a fraction of a second. On at least one firmware (used on some Gigabyte boards), setting use_graphics_for linux is required to avoid a system hang when launching Linux via its EFI stub loader. To add to the default list, specify + as the first option, as in use_graphics_for + windows.
scan_driver_dirs directory path(s) Scans the specified directory or directories for EFI driver files. If rEFInd discovers .efi files in those directories, they're loaded and activated as drivers. This option sets directories to scan in addition to the drivers and drivers_arch subdirectories of the rEFInd installation directory, which are always scanned, if present.
scanfor internal, external, optical, netboot, hdbios, biosexternal, cd, and manual Tells rEFInd what methods to use to locate boot loaders. The internal, external, and optical parameters tell rEFInd to scan for EFI boot loaders on internal, external, and optical (CD, DVD, and Blu-ray) devices, respectively. The netboot option relies on the presence of the ipxe.efi and ipxe_discover.efi program files in the EFI/tools directory to assist with network (Preboot Execution Environment, or PXE) booting. Note that netboot is experimental. See the BUILDING.txt file for information on building the necessary binaries. The hdbios, biosexternal, and cd parameters are similar, but scan for BIOS boot loaders. (Note that the BIOS options scan more thoroughly and actively on Macs than on UEFI-based PCs; for the latter, only options in the firmware's boot list are scanned, as described on the Using rEFInd page.) The manual parameter tells rEFInd to scan the configuration file for manual settings. You can specify multiple parameters to have the program scan for multiple boot loader types. When you do so, the order determines the order in which the boot loaders appear in the menu. The default is internal, external, optical, manual on most systems, but internal, hdbios, external, biosexternal, optical, cd, manual on Macs.
uefi_deep_legacy_scan none or one of true, on, 1, false, off, or 0 Tells rEFInd how aggressively to scan for BIOS/CSM/legacy boot loaders on UEFI-based PCs. Ordinarily or if this option is set to false, off, or 0, rEFInd presents only those options that were available in the NVRAM when it launched. When uncommented with no option or with true, on, or 1 set, rEFInd adds every possible BIOS-mode boot device (of types specified by scanfor) as a BIOS/CSM/legacy boot option. This latter behavior is sometimes required to detect USB flash drives or hard disks beyond the first one.
scan_delay numeric (integer) value Imposes a delay before rEFInd scans for disk devices. Ordinarily this is not necessary, but on some systems, some disks (particularly external drives and optical discs) can take a few seconds to become available. If some of your disks don't appear when rEFInd starts but they do appear when you press the Esc key to re-scan, try uncommenting this option and setting it to a modest value, such as 2, 5, or even 10. The default is 0.
also_scan_dirs directory path(s) Adds the specified directory or directories to the directory list that rEFInd scans for EFI boot loaders when scanfor includes the internal, external, or optical options. Directories are specified relative to the filesystem's root directory. You may precede a directory path with a volume name and colon, as in somevol:/extra/path, to restrict the extra scan to a single volume. If you don't specify a volume name, this option is applied to all the filesystems that rEFInd scans. If a specified directory doesn't exist, rEFInd ignores it (no error results). The default value is boot, which is useful for locating Linux kernels when you have an EFI driver for your Linux root (/) filesystem. To add to, rather than replace, the default value, specify + as the first item in the list, as in also_scan_dirs +,loaders.
dont_scan_volumes or don't_scan_volumes filesystem or partition label(s) Adds the specified volume or volumes to a volume "blacklist"—these filesystems are not scanned for EFI boot loaders. This may be useful to keep unwanted EFI boot entries, such as for an OS recovery partition, from appearing on the main list of boot loaders. You can identify a volume by its filesystem name, its GPT volume name, or by its GPT unique GUID value. The default value is LRS_ESP, to keep the Lenovo Windows recovery volume from appearing. (This volume should get its own tools icon instead—see the showtools token.) You can use dont_scan_volumes to hide disks or partitions from legacy-mode scans, too. In this case, you can enter any part of the description that appears beneath the icons to hide entries that include the string you specify.
dont_scan_dirs or don't_scan_dirs directory path(s) Adds the specified directory or directories to a directory "blacklist"—these directories are not scanned for boot loaders. You may optionally precede a directory path with a volume name and a colon to limit the blacklist to that volume; otherwise all volumes are affected. For instance, EFI/BOOT prevents scanning the EFI/BOOT directory on all volumes, whereas ESP:EFI/BOOT blocks scans of EFI/BOOT on the volume called ESP but not on other volumes. You can use a filesystem unique GUID, as in 2C17D5ED-850D-4F76-BA31-47A561740082, in place of a volume name. This token may be useful to keep duplicate boot loaders out of the menu; or to keep drivers or utilities out of the boot menu, if you've stored them in a subdirectory of EFI. This option takes precedence over also_scan_dirs; if a directory appears in both lists, it will not be scanned. To add directories to the default list rather than replace the list, specify + as the first option, as in dont_scan_dirs + EFI/dontscan. The default for this token is EFI/tools, EFI/tools/memtest86, EFI/tools/memtest, EFI/memtest86, EFI/memtest,
dont_scan_files or don't_scan_files filename(s) Adds the specified filename or filenames to a filename "blacklist" for OS loaders—these files are not included as boot loader options even if they're found on the disk. This is useful to exclude support programs (such as shim.efi and MokManager.efi) and drivers from your OS list. The default value is shim.efi, shim-fedora.efi, shimx64.efi, PreLoader.efi, TextMode.efi, ebounce.efi, GraphicsConsole.efi, MokManager.efi, HashTool.efi, HashTool-signed.efi, fb{arch}.efi (where {arch} is the architecture code, such as x64). You can add a pathname and even a volume specification (filesystem name, partition name, or partition unique GUID), as in ESP:/EFI/BOOT/backup.efi, /boot/vmlinuz-bad, to block the boot loaders only in those specified locations. To add files to the default list rather than replace the list, specify + as the first option, as in dont_scan_files + badloader.efi.
dont_scan_tools or don't_scan_tools filename(s) Adds the specified filename or filenames to a filename "blacklist" for tools—these files are not included as tools (second-line options) even if they're found on the disk and are specified to be included via showtools. This is useful to trim an overabundance of tools. For instance, if you install multiple Linux distributions, you may end up with multiple MokManager entries, but you'll need just one. You can add a pathname and even a volume specification (filesystem name, partition name, or partition unique GUID), as in ESP:/EFI/tools/shellx64.efi, EFI/ubuntu/mmx64.efi, to block the tools only in those specified locations. The default value is an empty list (nothing is excluded).
windows_recovery_files filename(s) Adds the specified filename or filenames that will be recognized as Windows recovery tools and presented as such on the second row, if windows_recovery is among the options to showtools. The filename must include a complete path and may optionally include a filesystem label, as in LRS_EFI:\EFI\Microsoft\Boot\LrsBootmgr.efi. Whatever you specify here is added to the dont_scan_files list. The default value is EFI\Microsoft\Boot\LrsBootmgr.efi. If you specify + as the first option, the following options will be added to the default rather than replace it.
scan_all_linux_kernels none or one of true, on, 1, false, off, or 0 When uncommented or set to true, on, or 1, causes rEFInd to add Linux kernels (files with names that begin with vmlinuz, bzImage, or kernel) to the list of EFI boot loaders, even if they lack .efi filename extensions. This simplifies use of rEFInd on most Linux distributions, which usually provide kernels with EFI stub loader support but don't give those kernels names that end in .efi. Of course, the kernels must still be stored on a filesystem that rEFInd can read, and in a directory that it scans. (Drivers and the also_scan_dirs options can help with those issues.) This option is enabled by default; to disable this feature, you must uncomment this token and set it to false or one of its synonyms (off or 0).
fold_linux_kernels none or one of true, on, 1, false, off, or 0 When uncommented or set to true, on, or 1, causes rEFInd to "fold" all Linux kernels in a given directory into a single main-menu icon. Selecting that icon launches the most recent kernel. To launch an older kernel, you must press F2, Insert, or Tab; older kernels appear on the resulting submenu display. (You can type, as root, touch /boot/vmlinuz-{whatever}, to make /boot/vmlinuz-{whatever} your default kernel in a directory.) If you prefer to see all your kernels in the main menu, set this option to false, off, or 0. Note that this option is new with version 0.9.0, which changes the default behavior; earlier versions of rEFInd behaved as if fold_linux_kernels false was set.
extra_kernel_version_strings comma-delimited list of strings For the benefit of Linux distributions, such as Arch, that lack version numbers in their kernel filenames but that can provide multiple kernels, you can specify strings that can treated like version numbers. For instance, for Arch you might set this to linux-lts,linux; thereafter, the vmlinuz-linux-lts kernel will match to an initrd file containing the string linux-lts and vmlinuz-linux will match an initrd file with a filename that includes linux, but not linux-lts. Note that, if one specified string is a subset of the other (as in this example), the longer substring must appear first in the list. Also, if a filename includes both a specified string and one or more digits, the match covers both; for instance, vmlinuz-linux-4.8 would match an initrd file with a name that includes linux-4.8. The default is to do no extra matching.
max_tags numeric (integer) value Limits the number of tags that rEFInd will display at one time. If rEFInd discovers more loaders than this value, they're shown in a scrolling list. The default value is 0, which imposes no limit.
default_selection a substring of a boot loader's title, +, or a numeric position; optionally followed by two times in HH:MM format Sets the default boot OS based on the loader's title, which appears in the main menu beneath the icons when you select the loader. This token takes one or three variables. The first variable is a set of one or more identifiers. If you specify more than one or if the identifier contains a space, it must be in quotation marks. If more than one identifier is present, they must be specified as a comma-separated list, all within a single set of quotation marks. For instance, default_selection "alpha,beta" will launch alpha if it's available, and beta if alpha is not available but beta is. Each identifier can be any one of three things:
  • The symbol +, which refers to the previously-launched boot entry. rEFInd stores (in NVRAM) the name of a boot entry before launching it, and effectively substitutes that stored string for the + in the default_selection line the next time rEFInd launches, then matches it as a string, as described next....
  • Any string, which is matched against boot descriptions. Note that rEFInd matches substrings, so you don't need to specify the complete description string, just a unique substring. Thus, default_selection vmlinuz matches vmlinuz, boot\vmlinuz-5.3.0-22-generic, or any other string that includes vmlinuz. rEFInd stops searching when it finds the first match. Because rEFInd sorts entries within a directory in descending order by file modification time, if you specify a directory (or volume name, for loaders in a partition's root directory) as the default_selection, the newest loader in that directory will be the default. As a special case, one-character strings are matched against the first character of the description, except for digits.
  • A digit (1 to 9), in which case the boot loader at that position in the boot list is launched. For instance, default_selection 2 makes the second boot entry the default.
You may optionally follow the match string by two times, in 24-hour format, in which case the entry applies only between those two times. For instance, default_selection Safety 1:30 2:30 boots the entry called Safety by default between the hours of 1:30 and 2:30. These times are specified in whatever format the motherboard clock uses (local time or UTC). If the first value is larger than the second, as in 23:00 1:00, it is interpreted as crossing midnight—11:00 PM to 1:00 AM in this example. The last default_selection setting takes precedence over preceding ones if the time value matches. Thus, you can set a main default_selection without a time specification and then set one or more others to override the main setting at specific times. If you do not specify a default_selection, rEFInd attempts to boot the previously-booted entry, or the first entry if there's no record of that or if the previously-booted entry can't be found.
enable_and_lock_vmx none or one of true, on, 1, false, off, or 0 When set to true or a synonym, enable the CPU's VMX bit and lock the MSR. This configuration is necessary for some hypervisors (notably Microsoft's Hyper-V) to function properly. Activating it on other CPUs will, at best, have no effect, and could conceivably crash the computer, so enable it at your own risk! If your firmware supports activating these features, you should use it instead; this option is provided for users whose firmware does not provide this functionality. (Many Macs lack this configurability, for instance.) The default is false.
spoof_osx_version string (10.9 suggested) On some Macs, this option causes rEFInd to tell the firmware that the specified version of macOS is being launched, even when another OS is selected. The effect is that the firmware may initialize hardware differently, which may have beneficial (or detrimental) results. If your Mac's video output isn't working normally, this option may help. On the other hand, keyboards and mice are known to sometimes stop functioning if this option is used, so you shouldn't use it unnecessarily. This option has no effect on non-Apple hardware. The default is to not use this feature.
csr_values List of hexadecimal values Specifies values that may be set via the csr_rotate tool for Apple's System Integrity Protection (SIP). SIP stores values in NVRAM to set restrictions on what users (even root) may do in macOS 10.11. If you want to be able to control these restrictions in rEFInd, you must set the values you want to use here and set csr_rotate on the showtools line (which must also be uncommented). Note that values are specified in hexadecimal, with no leading 0x or other hexadecimal indicator. SIP is described in more detail on many Web sites, such as here.
include filename Includes the specified file into the current configuration file. Essentially, the included file replaces the include line, so positioning of this token is important if the included file includes options that contradict those in the main file. The included file must reside in the same directory as the rEFInd binary and the main configuration file. This option is valid only in the main configuration file; included files may not include third-tier configuration files.

As an example of rEFInd configuration, consider the following refind.conf file:

# Sample refind.conf file
timeout 5
banner custom.bmp
scan_driver_dirs drivers,EFI/tools/drivers
scanfor manual,external,optical
default_selection elilo

This example sets a timeout of 5 seconds; loads a custom graphic file called custom.bmp from the directory in which the rEFInd binary resides; scans the drivers and EFI/tools/drivers directories for EFI drivers; uses manual boot loader configuration but also scans for external EFI boot loaders and EFI boot loaders on optical discs; and sets the default boot loader to the first loader found that includes the string elilo. Of course, since this file specifies use of manual boot loader configuration, it's not complete; you'll need to add at least one OS stanza to be able to boot from anything but an external disk or optical drive, as described shortly.

Creating Manual Boot Stanzas

Manual boot stanzas in rEFInd are similar to those in GRUB Legacy, GRUB 2, or ELILO. You can use them to add EFI boot loaders to those that are auto-detected. rEFInd does not yet support manual boot stanzas for BIOS-mode boot loaders. You also cannot modify the auto-detected options; if you just want to tweak one OS's configuration, you have several options:

Each OS stanza begins with the keyword menuentry, a name for the entry, and an open curly brace ({). Subsequent lines constitute the bulk of the stanza, which concludes with a line containing nothing but a close curly brace (}). Table 2 summarizes the keywords that you can include in a stanza.

Table 2: OS stanza definitions in refind.conf
Token Possible parameters Explanation
menuentry name for the entry Sets the name that's displayed along with the icon for this entry. If the name should contain a space, it must be enclosed in quotes. Following the name, an open curly brace ({) ends the menuentry line.
volume filesystem label, partition label, or GUID value Sets the volume that's used for subsequent file accesses (by icon and loader, and by implication by initrd if loader follows volume). You pass this token a filesystem's label, a partition's label, or a partition's GUID. A filesystem or partition label is typically displayed under the volume's icon in file managers and rEFInd displays it on its menu at the start of the identifying string for an auto-detected boot loader. If this label isn't unique, the first volume with the specified label is used. The matching is nominally case-insensitive, but on some EFIs it's case-sensitive. If a volume has no label, you can use a partition GUID number. If this option is not set, the volume defaults to the one from which rEFInd launched.
loader filename Sets the filename for the boot loader. You may use either Unix-style slashes (/) or Windows/EFI-style backslashes (\) to separate directory elements. In either case, the references are to files on the ESP from which rEFInd launched or to the one identified by a preceding volume token. The filename is specified as a path relative to the root of the filesystem, so if the file is in a directory, you must include its complete path, as in \EFI\myloader\loader.efi. This option should normally be the first in the body of an OS stanza; if it's not, some other options may be ignored. An exception is if you want to boot a loader from a volume other than the one on which rEFInd resides, in which case volume should precede loader.
initrd filename Sets the filename for a Linux kernel's initial RAM disk (initrd). This option is useful only when booting a Linux kernel that includes an EFI stub loader, which enables you to boot a kernel without the benefit of a separate boot loader. When booted in this way, though, you must normally pass an initrd filename to the boot loader. You must specify the complete EFI path to the initrd file with this option, as in initrd EFI/linux/initrd-3.3.0-rc7.img. You'll also have to use the options line to pass the Linux root filesystem, and perhaps other options (as in options "root=/dev/sda4 ro"). The initial RAM disk file must reside on the same volume as the kernel.
icon filename Sets the filename for an icon for the menu. If you omit this item, a default icon will be used, based on rEFInd's auto-detection algorithms. The filename should be a complete path from the root of the current directory, not relative to the default icons subdirectory or the one set via icons_dir.
ostype MacOS, Linux, ELILO, Windows, XOM Determines the options that are available on a sub-menu obtained by pressing the Insert key with an OS selected in the main menu. If you omit this option, rEFInd selects options using an auto-detection algorithm. Note that this option is case-sensitive.
graphics on or off Enables or disables a graphical boot mode. This option has an effect only on Macintoshes; UEFI PCs seem to be unaffected by it.
options options passed to the boot loader Pass arbitrary options to your boot loader with this line. Note that if the option string should contain spaces (as it often should) or characters that should not be modified by rEFInd's option parser (such as slashes or commas), it must be enclosed in quotes. If you must include quotes in an option, you can double them up, as in my_opt=""with quotes"", which passes my_opt="with quotes" as an option.
disabled none Disable an entry. This is often easier than commenting out an entire entry if you want to temporarily disable it.
submenuentry submenu entry name and tokens This keyword identifies a submenu entry, as described in more detail shortly.

As an example, consider the following entries:

menuentry "Ubuntu" {
    loader /EFI/ubuntu/grubx64.efi

menuentry Arch {
    icon /EFI/refind/icons/os_arch.png
    volume ARCHBOOT
    loader /vmlinuz-linux
    initrd /initramfs-linux.img
    options "root=/dev/sda3 ro"

menuentry "Windows via shell script" {
    icon \EFI\refind\icons\os_win.png
    loader \EFI\tools\shell.efi
    options "fs0:\EFI\tools\launch_windows.nsh"

This example sets up three entries: one for Ubuntu, one for Arch Linux, and one to launch a shell script. Note that the final entry uses different directory separators from the first two, simply to demonstrate the fact that it's possible. (The form of directory separators in options lines is important, though, because the program being launched may expect a particular directory separator character.) The Ubuntu entry sets no icon, since rEFInd will note that the boot loader is stored in the ubuntu directory, and it will automatically find the appropriate Ubuntu icon (os_ubuntu.png). This entire entry is, however, disabled, so no matching icon will appear when you reboot unless you first comment out or delete the disabled line.

The Arch entry begins with an icon specification to be sure that the icon is loaded from the same volume as rEFInd. (If the icon were stored on the same filesystem as the kernel, you'd place the icon line after the volume line.) This entry uses the volume token to tell rEFInd to load the kernel and initial RAM disk file from the filesystem or partition called ARCHBOOT. It passes the filename for an initial RAM disk using the initrd line and free-form options using the options line.

The Windows via shell script entry may seem puzzling, but its purpose is to launch an OS (Windows in this case) after performing additional pre-boot initialization, which is handled by an EFI shell script. This works because you can pass the name of a shell script to an EFI shell—the script is named on the stanza's options line, using EFI file notation. The shell script, in turn, does whatever it needs to do and then launches the OS's boot loader:

mm 0003003E 8 -pci

This example writes data to the computer's PCI bus via the EFI shell's mm command and then launches Windows. Chances are you won't need to engage in such operations, and I do not recommend you try this exact example unless you know what you're doing! This command was required to activate the video hardware prior to booting Windows on a computer of a person with whom I corresponded, but such needs are rare. (Using the spoof_osx_version option in rEFInd 0.9.3 and later may also help with some such problems, at least on Macs.) A few pointers on finding addresses for your hardware can be found in this post.

You can combine these OS stanzas with the global refind.conf options presented earlier. The result would contain just two entries on the rEFInd boot menu (for Arch and Windows, since the Ubuntu entry is disabled), unless rEFInd found other boot options on an external or optical disk.

Creating Submenu Entries

As described on the Using rEFInd page, rEFInd can present a menu of options for certain loader tags when you press the Insert, F2, or + key. rEFInd does this automatically when it detects macOS or ELILO boot loaders, when you set the OS type via the ostype option, or when booting a Linux kernel directly. The macOS boot loader, in particular, accepts various options that you can use to boot in various ways.

Sometimes, you might want to create your own custom submenu entries, and rEFInd enables you to do this. To create a custom submenu, you use the submenuentry keyword inside a menuentry stanza. Normally, you'll set the submenu definitions after you've set the main menu options, since the submenu options take the main menu options as defult, and so the main options must be set first. Like a menuentry stanza, a submenuentry definition begins with the keyword, the name of the item, and an open curly brace ({). It continues until a close curly brace (}). A submenu definition can use the keywords described in Table 3. Except as otherwise noted, using an option of a given name completely overrides the setting in the main stanza.

Table 3: Submenu keywords in refind.conf
Token Possible parameters Explanation
submenuentry name for the entry Sets the name that's displayed for this entry on the submenu page. If the name should contain a space, it must be enclosed in quotes. Following the name, an open curly brace ({) ends the submenuentry line.
loader filename Sets the filename for the boot loader, as described in Table 2. Note that the loader is read from whatever filesystem is specified by the main stanza's volume option, provided that option precedes the submenu definition.
initrd filename Sets the filename for a Linux kernel's initial RAM disk (initrd), as described in Table 2. If you want to eliminate the initrd specification, you should use this keyword alone, with no options. You might do this because your main entry is for a Linux kernel with EFI stub support and this submenu entry launches ELILO, which sets the initrd in its own configuration file.
graphics on or off Enables or disables a graphical boot mode, as described in Table 2.
options options passed to the boot loader Pass arbitrary options to your boot loader with this line, as described in Table 2. As with initrd, you can eliminate all options by passing this keyword alone on a line.
add_options options passed to the boot loader This token works just like options, except that instead of replacing the default options, it causes the specified options to be added to those specified in the main stanza listing's options line.
disabled none Disable a submenu entry. This is often easier than commenting out an entire entry if you want to temporarily disable it.

The following menu entry illustrates the use of submenu entries. This is a variant of the second entry presented earlier:

menuentry Arch {
    icon /EFI/refind/icons/os_arch.png
    loader /vmlinuz-linux
    initrd /initramfs-linux.img
    options "root=/dev/sda3 ro"
    submenuentry "single-user mode" {
        add_options "single"
    submenuentry "Use fallback initrd" {
        initrd /initramfs-linux-fallback.img
    submenuentry "boot via SYSLINUX" {
        loader \EFI\syslinux\syslinux.efi

The main menu item for this entry won't look different with the submenus defined than without them; but if you press the F2 or Insert key, you'll see the submenu items:

Manually defining submenus enables you to customize
    your boot options.

The main menu item appears at the top of the list—Boot using default options. The three submenus defined in this example's configuration file appear next, enabling you to launch in single-user mode, boot the standard kernel with the fallback initrd file, or boot via SYSLINUX, respectively. Submenus also include an item called Return to Main Menu that does just as it says. (Alternatively, you can return to the main menu by pressing the Esc key.)

This example illustrates some of the things you can do with submenu entries:

Adjusting the Default Boot Option

Just before launching an OS, rEFInd stores the description in the EFI variable PreviousBoot with a GUID of 36d08fa7-cf0b-42f5-8f14-68df73ed3740. The next time rEFInd launches, it reads that same variable and sets the default boot loader to that value, if it's still available and if the first item in default_selection in the refind.conf file is a plus sign (+).

Under Linux, the variable that rEFInd uses to store this information is accessible as /sys/firmware/efi/efivars/PreviousBoot-36d08fa7-cf0b-42f5-8f14-68df73ed3740. Thus, you can back up this value, modify it, and write it back out to adjust your next-booted OS. Getting this string just right can be a bit tricky, though, and if the kernel doesn't like its format, it will not let you modify the variable. If you try to modify the variable, be aware that it's stored in UTF-16 format. As with the default_selection token in refind.conf, you can enter any substring that uniquely identifies the entry you want to boot.

In principle, you should be able to use a similar procedure to force rEFInd to boot another OS by default in any other OS that supports writing EFI runtime variables. Unfortunately, I don't know the mechanisms used for this task in Windows, macOS, FreeBSD, or any other OS.

If you want to consistently boot a particular OS by default and ignore the previous boot, you can use default_selection, but omit the + at the start of the line.

copyright © 2012–2020 by Roderick W. Smith

This document is licensed under the terms of the GNU Free Documentation License (FDL), version 1.3.

If you have problems with or comments about this Web page, please e-mail me at Thanks.

Go to the main rEFInd page

Learn about how to use EFI drivers with rEFInd

Return to my main Web page.