# How Ventoy Resolves the Configuration File Search Path When Multiple Config Files Exist

> Discover how Ventoy resolves the configuration file search path. Learn its priority-ordered search algorithm and fallback methods for seamless boot.

- Repository: [longpanda/Ventoy](https://github.com/ventoy/Ventoy)
- Tags: internals
- Published: 2026-03-01

---

**Ventoy implements a deterministic, priority-ordered search algorithm in [`INSTALL/grub/grub.cfg`](https://github.com/ventoy/Ventoy/blob/main/INSTALL/grub/grub.cfg) that iterates through a hard-coded list of candidate paths and stops at the first existing file, falling back to systemd-boot or Syslinux configurations only when no GRUB configuration is detected.**

When booting from ISO images, the open-source multiboot tool Ventoy must determine which configuration file to load without assuming a single location. According to the ventoy/Ventoy repository source code, the bootloader resolves the configuration file search path through a deterministic algorithm that prioritizes conventional GRUB locations before attempting alternative bootloader formats.

## The Deterministic Search Algorithm in [`INSTALL/grub/grub.cfg`](https://github.com/ventoy/Ventoy/blob/main/INSTALL/grub/grub.cfg)

The search logic is implemented in the install-time GRUB script at [`INSTALL/grub/grub.cfg`](https://github.com/ventoy/Ventoy/blob/main/INSTALL/grub/grub.cfg). The algorithm follows a strict sequence:

1. **Initialization**: The flag `vtback_cfg_find` is reset to `0` at line 848.
2. **Primary GRUB-CFG search**: A `for` loop iterates over hard-coded candidate paths. The first file that exists (tested with `-e`) triggers `configfile "$cfg"` and breaks the loop (lines 848-855).
3. **Fallback checks**: If no GRUB config is found, Ventoy checks for systemd-boot environments (lines 857-865) and then Syslinux configurations (lines 869-877).
4. **Final handling**: If all searches fail, the script continues to the next boot entry (lines 879-880).

## Priority Order of Configuration File Locations

The candidate list in the primary loop is ordered from most conventional to least common locations:

```sh
"/boot/grub/grub.cfg" \
"/EFI/BOOT/grub.cfg" \
"/EFI/debian/grub.cfg" \
"EFI/boot/grub.cfg" \
"efi/boot/grub.cfg" \
"/grub/grub.cfg" \
"EFI/BOOT/BOOTX64.conf"

```

Ventoy stops at the **first** file that returns true for the existence test `-e`. Consequently, if an ISO contains both [`/boot/grub/grub.cfg`](https://github.com/ventoy/Ventoy/blob/main//boot/grub/grub.cfg) and [`/EFI/BOOT/grub.cfg`](https://github.com/ventoy/Ventoy/blob/main//EFI/BOOT/grub.cfg), the former is chosen because it appears earlier in the list.

## Fallback Mechanisms for Alternative Bootloaders

When the primary GRUB search returns no results (`vtback_cfg_find` remains `0`), Ventoy executes secondary detection routines.

### systemd-boot Detection

Ventoy checks for a systemd-boot environment by verifying the presence of [`loader/loader.conf`](https://github.com/ventoy/Ventoy/blob/main/loader/loader.conf) and `loader/entries`. When detected, it invokes the `vt_systemd_menu` routine and sets `vtback_cfg_find` to indicate success (lines 857-865 in [`INSTALL/grub/grub.cfg`](https://github.com/ventoy/Ventoy/blob/main/INSTALL/grub/grub.cfg)).

### Syslinux Configuration Fallback

If systemd-boot is not present, Ventoy looks for classic Syslinux configuration files such as [`isolinux/syslnx64.cfg`](https://github.com/ventoy/Ventoy/blob/main/isolinux/syslnx64.cfg) or [`syslinux/porteus.cfg`](https://github.com/ventoy/Ventoy/blob/main/syslinux/porteus.cfg). Upon finding a valid file, it calls `syslinux_configfile` and marks the configuration as found (lines 869-877).

## Integration with [`ventoy.json`](https://github.com/ventoy/Ventoy/blob/main/ventoy.json) Plugin Configuration

Separate from the boot configuration search, Ventoy loads plugin settings from [`/ventoy/ventoy.json`](https://github.com/ventoy/Ventoy/blob/main//ventoy/ventoy.json). In [`GRUB2/MOD_SRC/grub-2.04/grub-core/ventoy/ventoy_plugin.c`](https://github.com/ventoy/Ventoy/blob/main/GRUB2/MOD_SRC/grub-2.04/grub-core/ventoy/ventoy_plugin.c) (lines 2478-2483), the code opens this file using `ventoy_grub_file_open`, reads its content, and parses the JSON. If the file is missing, the function returns `GRUB_ERR_NONE` and continues booting without error. This follows the same "open-if-present-else-ignore" philosophy but does not interfere with the boot-config search order.

## Practical Code Examples

### Customizing the Search Order

To append a custom path to the existing candidate list, modify the `for` loop in [`INSTALL/grub/grub.cfg`](https://github.com/ventoy/Ventoy/blob/main/INSTALL/grub/grub.cfg):

```sh
for cfg in "/boot/grub/grub.cfg" "/EFI/BOOT/grub.cfg" \
           "/EFI/debian/grub.cfg" "EFI/boot/grub.cfg" \
           "efi/boot/grub.cfg" "/grub/grub.cfg" \
           "EFI/BOOT/BOOTX64.conf" "/my/custom/path.cfg"; do
    if [ -e "$cfg" ]; then
        set vtback_cfg_find=1
        configfile "$cfg"
        break
    fi
done

```

### Capturing the Chosen Configuration Path

To store the exact path of the selected configuration for debugging:

```sh
if [ -e "$cfg" ]; then
    set vtback_cfg_find=1
    set vt_chosen_cfg="$cfg"
    configfile "$cfg"
    break
fi

```

The variable `$vt_chosen_cfg` now holds the path that was loaded.

### Adding a Custom Bootloader Fallback

Extend the secondary fallback block to support additional loaders:

```sh
if [ $vtback_cfg_find -eq 0 ]; then
    if [ -f (loop)/myloader/loader.cfg ]; then
        echo "Launching custom loader"
        configfile (loop)/myloader/loader.cfg
        set vtback_cfg_find=1
    fi
fi

```

## Summary

- Ventoy uses a **deterministic, ordered search** through a hard-coded list of GRUB configuration paths in [`INSTALL/grub/grub.cfg`](https://github.com/ventoy/Ventoy/blob/main/INSTALL/grub/grub.cfg).
- The algorithm stops at the **first existing file** using the `-e` test, ensuring predictable behavior regardless of how many configuration files exist in the ISO.
- If no GRUB config is found, Ventoy falls back to **systemd-boot** (via `vt_systemd_menu`) and then **Syslinux** (via `syslinux_configfile`) detection.
- The [`ventoy.json`](https://github.com/ventoy/Ventoy/blob/main/ventoy.json) plugin file is loaded separately through `ventoy_grub_file_open` in [`ventoy_plugin.c`](https://github.com/ventoy/Ventoy/blob/main/ventoy_plugin.c) and does not affect the boot configuration search priority.

## Frequently Asked Questions

### What happens if multiple GRUB configuration files exist in the same ISO?

Ventoy selects the first file that exists according to the priority list defined in [`INSTALL/grub/grub.cfg`](https://github.com/ventoy/Ventoy/blob/main/INSTALL/grub/grub.cfg). If [`/boot/grub/grub.cfg`](https://github.com/ventoy/Ventoy/blob/main//boot/grub/grub.cfg) and [`/EFI/BOOT/grub.cfg`](https://github.com/ventoy/Ventoy/blob/main//EFI/BOOT/grub.cfg) both exist, the former takes precedence because it appears earlier in the `for` loop iteration (lines 848-855).

### Can I customize the configuration file search order?

Yes. You can modify the `for cfg in …` loop in [`INSTALL/grub/grub.cfg`](https://github.com/ventoy/Ventoy/blob/main/INSTALL/grub/grub.cfg) to add, remove, or reorder candidate paths. The search respects the first-match-wins principle, so placing a custom path earlier in the list ensures it takes priority over default locations.

### How does Ventoy handle ISOs that use systemd-boot instead of GRUB?

If the primary GRUB search fails (`vtback_cfg_find` remains `0`), Ventoy checks for systemd-boot markers ([`loader/loader.conf`](https://github.com/ventoy/Ventoy/blob/main/loader/loader.conf) and `loader/entries`). When found, it invokes `vt_systemd_menu` to handle the boot process (lines 857-865), bypassing the need for a GRUB configuration file entirely.

### Does the presence of [`ventoy.json`](https://github.com/ventoy/Ventoy/blob/main/ventoy.json) affect which boot configuration is loaded?

No. The [`ventoy.json`](https://github.com/ventoy/Ventoy/blob/main/ventoy.json) file is loaded independently by [`ventoy_plugin.c`](https://github.com/ventoy/Ventoy/blob/main/ventoy_plugin.c) (lines 2478-2483) for plugin settings and follows a separate existence check. It does not influence the priority order or selection logic for GRUB, systemd-boot, or Syslinux configuration files.