Ventoy Administrator & Developer Guide

Ventoy is a cross-firmware, cross-architecture bootable USB tool that eliminates the traditional extract-and-write workflow for live media. Install Ventoy once to a USB drive, then copy ISO/WIM/IMG/VHD/VHDX/EFI files directly onto the data partition and boot them without extraction. The project is built around a heavily modified GRUB2 core, an EDK2-based UEFI application, a modified iPXE for network boot, and a modified wimboot for Windows PE — all coordinated by shell-based installers and a suite of C-language platform tools.

This guide is the operational and architectural reference for engineers who deploy, maintain, build, package, or extend Ventoy. It covers the full boot chain from firmware handoff through image selection and OS handover, every component in the 101-module codebase, the build system and cross-compilation toolchains, the plugin/configuration architecture, the security model including Secure Boot enrollment, and the distro hook system that provides compatibility with 900+ Linux/BSD/Windows distributions. A reader who finishes this guide should be able to rebuild Ventoy from a clean host, execute a corporate rollout across hundreds of machines, diagnose firmware-level boot failures, and navigate the 2,772-file source tree with confidence.

Project vitals:

2. Architecture Overview

2.1 High-Level System Diagram

 +---------------------------USB DRIVE----------------------------+
 |                                                                 |
 |  Partition 1: "Ventoy" (exFAT/NTFS/ext)                       |
 |  +-----------+  +-----------+  +-----------+  +-----------+   |
 |  | file1.iso |  | file2.wim |  | file3.vhd |  | file4.img |   |
 |  +-----------+  +-----------+  +-----------+  +-----------+   |
 |  /ventoy/ventoy.json    (optional plugin config)               |
 |  /ventoy/theme/         (optional GRUB theme)                  |
 |                                                                 |
 |  Partition 2: "VTOYEFI" (32MB FAT16)                           |
 |  /grub/grub.cfg         /grub/i386-pc/     /grub/x86_64-efi/  |
 |  /grub/arm64-efi/       /grub/mips64el-efi/                    |
 |  /EFI/BOOT/             /ventoy/           /tool/              |
 |  /ENROLL_THIS_KEY_IN_MOKMANAGER.cer                            |
 +-----------------------------------------------------------------+
 
 MBR/GPT Boot Sector
        |
        v
 +--- BIOS Path --------+    +---- UEFI Path -------------------+
 | MBR boot code         |    | Firmware loads EFI app from       |
 | loads GRUB2 core.img  |    | VTOYEFI partition                 |
 | (i386-pc)             |    | EDK2 Ventoy EFI → GRUB2 EFI     |
 +------------------------+    +------------------------------------+
        |                              |
        v                              v
 +--- GRUB2 (Modified) -------------------------------------------+
 | grub.cfg → enumerate ISOs → display menu                        |
 | User selects image → Ventoy GRUB commands load it               |
 +------------------------------------------------------------------+
        |                    |                    |
        v                    v                    v
   Linux/BSD ISO        Windows WIM          VHD/VHDX
   (loopback mount      (wimboot 2.7.3       (ventoy_vdisk
    + distro hook)       modified)            via disk map)

Note

Ventoy's architecture is fundamentally a boot chain orchestrator. Every component — GRUB2, EDK2, iPXE, wimboot — is a fork of an upstream project with Ventoy-specific patches applied. The modifications are substantial (custom GRUB commands, EFI protocol handlers, disk virtualization layers) and cannot be trivially rebased onto newer upstream releases.

2.2 Boot Chain — BIOS Legacy Path

1. MBR boot sector executes, loads GRUB2 core.img from the gap between the MBR and the first partition (or from a dedicated boot image area)
2. GRUB2 (i386-pc) initializes with Ventoy-modified grub_main() that injects custom prefix/root handling via ventoy_env_write_root()
3. For disks exceeding BIOS addressing limits, ventoy_legacy_limit_workaround() activates: loads ventoy.disk.img.xz via loopback to work around INT13h constraints
4. grub.cfg on VTOYEFI partition runs, enumerating bootable files on the data partition
5. Menu is displayed; GRUB theme and language loaded via vt_load_menu_lang
6. On image selection, Ventoy GRUB modules handle the image type (ISO loopback, WIM chain, VHD map, etc.)
7. Control transfers to the target OS bootloader

2.3 Boot Chain — UEFI Path

1. UEFI firmware locates the FAT partition marked as EFI System Partition (VTOYEFI) and loads the Ventoy EFI application
2. EDK2 Ventoy EFI application (built from EDK2/edk2_mod/ against edk2-stable201911) initializes:
   • VDiskChain: virtual disk protocol for VHD/VHDX boot
   • VtoyUtil: utility protocols for UEFI environment manipulation
3. EDK2 application chain-loads GRUB2 EFI (architecture-specific: x86_64-efi, arm64-efi, or mips64el-efi)
4. GRUB2 EFI proceeds identically to the BIOS path from step 4 onward
5. For Secure Boot: the Ventoy MOK key must be enrolled first via MokManager (one-time operation)

2.4 Boot Chain — Windows WIM Path

1. GRUB2 identifies a WIM file (or ISO containing sources/boot.wim)
2. wimboot (modified version 2.7.3, from wimboot/wimboot-2.7.3/) is loaded
3. wimboot extracts bootmgr.exe from the compressed bootmgr file
4. A virtual disk is created in memory containing the WIM and required boot files
5. bootmgr.exe executes, loading Windows PE from the WIM
6. The vtoyjump component (vtoyjump/vtoyjump/) handles boot-time hooks: XZ decompression of payloads and disk/partition mapping so Windows PE can find the source ISO/WIM on the Ventoy data partition

2.5 Boot Chain — Network (iPXE) Path

1. iPXE (modified, based on commit 3fe683e, from IPXE/ipxe_mod_code/ipxe-3fe683e/) provides PXE network boot
2. The ventoy_boot_vdisk() function enables VHD boot over network
3. iPXE can chain-load Ventoy's GRUB2 or directly boot network-hosted images
4. Useful for diskless workstation deployments where images are served from a network share

2.6 Boot Chain — Unix/BSD Path

1. Custom geom_ventoy kernel modules provide virtual block device access for BSD-family systems
2. Precompiled modules cover: FreeBSD 9.x through 15.x, DragonFly BSD, MidnightBSD, pfSense, ClonOS
3. Source in Unix/ — these are GEOM (FreeBSD disk framework) classes that present the ISO content as a native block device
4. The kernel module loads during early boot via the distro hook mechanism, enabling the BSD installer/live system to find its root filesystem on the Ventoy-mapped device

3. Repository Layout and Module Index

The repository contains 101 modules. Below is the complete map organized by functional area.

3.1 Core Boot Infrastructure

3.2 Installer Tools

3.3 Disk and Filesystem Utilities

3.4 Compression and Cryptography

3.5 System Support

3.6 Packaging and Distribution

3.7 Directory Purposes on VTOYEFI (Partition 2)

4. Component Deep Dive

4.1 GRUB2 Modifications

Ventoy forks GRUB2 2.04 with extensive modifications that go well beyond configuration. The changes are in two areas: core boot handling and custom Ventoy-specific commands.

Core modifications in grub-core/:

• ventoy_env_write_root() — Hooks into GRUB's root device resolution. Intercepts the standard root-setting logic to inject Ventoy's virtual disk mapping, ensuring GRUB can address files on loopback-mounted ISOs as if they were on a native block device.
• ventoy_legacy_limit_workaround() — Addresses BIOS INT13h disk size limits. When the USB drive exceeds the addressable range (typically 2TB for LBA48, but firmware-dependent), this function loads ventoy.disk.img.xz via GRUB's loopback mechanism, providing an alternative access path to disk content beyond the firmware limit.
• grub_main() patches — The modified main function adds Ventoy-specific prefix and root handling before GRUB's normal initialization sequence. This ensures the GRUB environment is correctly configured to find modules and configuration on the VTOYEFI partition regardless of how the firmware enumerated the USB device.
• vt_load_menu_lang — Runtime language switching. Reads language JSON files from the data partition and applies translations to the GRUB menu at display time.

Custom Ventoy GRUB commands (in grub-core/ventoy/ and grub-core/commands/):

These modules implement the image-type-specific boot logic:

• ISO loopback mount and chain-load for Linux live images
• WIM detection and wimboot handoff for Windows images
• VHD/VHDX virtual disk mapping
• IMG raw disk image boot
• EFI file direct execution
• Multi-image and persistence support
• Checksum verification of image files

The GRUB module set is architecture-specific. Each target (i386-pc, x86_64-efi, arm64-efi, mips64el-efi) gets its own compiled module directory on VTOYEFI.

4.2 EDK2 UEFI Application

Built against edk2-stable201911 (not the latest EDK2 — pinned for stability), the Ventoy UEFI application provides two key protocols:

VDiskChain:

• Implements a UEFI Block I/O Protocol that presents a VHD/VHDX file as a native UEFI block device
• Allows UEFI firmware to boot directly from virtual hard disk files without OS-level support
• Handles both fixed-size and dynamic VHD formats

VtoyUtil:

• Utility protocol for UEFI environment manipulation
• Provides functions for memory mapping, device path construction, and protocol installation
• Used by the GRUB2 EFI build to interface with Ventoy-specific UEFI services

The EDK2 build produces architecture-specific EFI applications that are placed in the /EFI/BOOT/ directory on VTOYEFI.

4.3 wimboot (Modified 2.7.3)

The wimboot fork handles Windows boot, which is the most complex boot path due to Windows' strict requirements:

1. bootmgr extraction — Windows ships bootmgr as a compressed PE executable. wimboot locates the embedded bootmgr.exe, decompresses it, and executes it directly.
2. Virtual disk creation — Constructs an in-memory virtual disk containing:
   • The WIM file (or a pointer to it on the USB)
   • BCD (Boot Configuration Data) store
   • Required boot fonts and resources
3. Memory mapping — Maps the virtual disk into the address space where bootmgr.exe expects to find its boot volume

The modifications over upstream wimboot are primarily in how the source WIM is located (on a Ventoy USB partition rather than a PXE server) and how the virtual disk interacts with Ventoy's disk mapping layer.

4.4 iPXE (Modified 3fe683e)

The iPXE fork adds ventoy_boot_vdisk() — a function that enables VHD boot over network. This allows a deployment where:

• The Ventoy USB provides the boot infrastructure
• VHD images are served from a network file server
• iPXE fetches the VHD and boots it via Ventoy's VDiskChain

This is primarily useful for enterprise thin-client or diskless workstation scenarios.

4.5 Windows Installer — Ventoy2Disk.exe

The Windows native installer is a Win32 application (22 source files, 519KB of C source) in Ventoy2Disk/Ventoy2Disk/.

Key source files and responsibilities:

Notable implementation details:

• XZ embedded decompression for core.img — the GRUB core image is stored compressed and decompressed at install time
• Both 32-bit and 64-bit builds; ARM64 version available for Windows on ARM devices
• Non-destructive install (-n flag) supports NTFS and ext2/3/4 filesystem shrink — resizes the existing filesystem, creates Ventoy partitions in the freed space, preserving existing data
• AlertSuppress.c runs in a separate thread, monitoring for and automatically dismissing Windows dialog boxes that appear when raw disk operations cause the OS to detect "unformatted" partitions

4.6 Linux GUI Installer

Four frontend variants share a common core in LinuxGUI/Ventoy2Disk/Core/:

GTK2/GTK3 (build_gtk.sh):

• Native desktop GUI using GTK widget toolkit
• GTK3 preferred; GTK2 as fallback for older distributions

QT5 (build_qt.sh):

• QT5 desktop GUI for KDE/QT-native desktop environments

WebUI (build.sh):

• civetweb-based web server (V2DServer)
• Provides a browser-based interface accessible at http://127.0.0.1:24680
• Fallback when no desktop toolkit is available (headless servers, minimal installs)

Launcher script VentoyGUI.{arch}:

• Probes toolkit availability in order: GTK3 → QT5 → GTK2 → WebUI
• Launches the first available frontend
• Architecture variants: x86_64, i386, aarch64, mips64el

4.7 Plugson — Plugin Configuration Server

Plugson is a civetweb-based (embedded HTTP, no SSL, no CGI) web application for managing Ventoy's JSON plugin configuration files.

Core source files in Plugson/src/:

Web UI (Plugson/www/):

• Built on AdminLTE 2.3.0 (Bootstrap 3 admin template)
• DataTables for tabular plugin configuration
• jQuery for DOM manipulation and AJAX
• Provides point-and-click management of all ventoy.json plugin sections

Plugson reads and writes JSON configuration files in the /ventoy/ directory on the USB data partition (Partition 1). It is launched from the installer GUI or manually via command line.

4.8 vtoyjump — Windows Boot-Time Hook

vtoyjump is a small C program that runs during Windows PE boot (before the full Windows environment loads). Its responsibilities:

• XZ decompression of compressed payloads needed during boot
• Disk and partition mapping so Windows PE can locate the source ISO/WIM on the Ventoy data partition
• Drive letter assignment for the Ventoy partition within the Windows PE environment

This is critical for Windows installations from ISO — Windows Setup needs to find the sources/install.wim inside the ISO, which requires the ISO content to be accessible as a mounted volume.

4.9 Disk Utilities

VtoyTool — Low-level operations: ISO sector mapping, disk geometry queries, partition offset calculations. Used by installer scripts to prepare the USB layout.

vtoycli — Command-line interface for partition operations. Key subcommand: partresize for Secure Boot partition adjustments (vtoycli partresize -s modifies the VTOYEFI partition layout).

vtoygpt — GPT partition table manipulation. Creates and modifies GUID Partition Tables for disks using GPT layout (required for disks >2TB, optional via -g flag for smaller disks).

vtoyfat — FAT filesystem I/O wrapper. Provides programmatic read/write access to the VTOYEFI FAT16 partition without OS-level mount operations.

5. Partition Layout and Disk Structure

5.1 Partition Table

Ventoy supports both MBR and GPT partition styles:

Important

4K native sector devices (4Kn) are not supported. Ventoy requires 512-byte logical sector drives. Most USB drives use 512e (512-byte emulation over 4K physical), which works fine. True 4Kn devices will fail during installation.

5.2 Partition 1 — Data Partition

Supported image formats on this partition: .iso, .wim, .img, .vhd, .vhdx, .efi, .vtoy (Ventoy auto-install), .vlnk (Ventoy link files).

5.3 Partition 2 — VTOYEFI

This partition is managed entirely by Ventoy. Users should not modify its contents manually. Ventoy upgrades replace this partition's contents while preserving Partition 1 data.

5.4 Reserved Space

The -r SIZE_MiB flag reserves space at the end of the disk, between the data partition and VTOYEFI. Use cases:

• Preserving a small partition for other tools (e.g., a persistent encrypted volume)
• Working around firmware bugs that misread the disk's last sectors

5.5 Install Modes

6. Build System

6.1 Build Environment Requirements

The build system is designed for Linux hosts. Cross-compilation toolchains are required for multi-architecture output.

Required toolchains:

Required libraries:

Build dependencies for sub-projects:

6.2 Build Pipeline

The master build orchestration is in INSTALL/all_in_one.sh and ventoy_pack.sh.

Build order:

1. prepare_env        Set up toolchains, create build directories
        |
2. GRUB2 build        grub-2.04 for all 4 architectures
        |              (i386-pc, x86_64-efi, arm64-efi, mips64el-efi)
        |
3. iPXE build         Network boot firmware
        |
4. EDK2 build         UEFI applications (VDiskChain, VtoyUtil)
        |
5. Utility builds     VtoyTool, vtoycli, vtoygpt, vtoyfat, FUSEISO,
        |              ExFAT, SQUASHFS, VBLADE, DMSETUP, LZIP, ZSTD
        |
6. wimboot build      Windows WIM boot loader
        |
7. Installer builds   Ventoy2Disk (Windows), LinuxGUI variants
        |
8. Plugson build      Plugin configuration server
        |
9. ventoy_pack.sh     Package everything into release archives

6.3 Release Packaging

ventoy_pack.sh produces:

6.4 Docker CI Build

docker_ci_build.sh provides a reproducible build environment:

1. Downloads all required cross-compilation toolchains
2. Installs build dependencies in a container
3. Runs the full build pipeline
4. Outputs release packages

This is the recommended build method for contributors — it eliminates host-specific toolchain version issues.

Note

The build system does not use CMake, Meson, or any modern build system generator. Each component has its own Makefile or build script. The all_in_one.sh script orchestrates them sequentially. Parallel builds of independent components are not implemented.

6.5 Building Individual Components

For development iteration, individual components can be rebuilt:

# GRUB2 only (all architectures)
cd GRUB2/MOD_SRC/grub-2.04
./autogen.sh
./configure --target=x86_64 --with-platform=efi
make

# EDK2 UEFI application
cd EDK2/edk2_mod
source edksetup.sh
build -a X64 -t GCC5 -p VentoyPkg/VentoyPkg.dsc

# Plugson
cd Plugson/src
make

# Windows installer (requires MinGW cross-compiler on Linux)
cd Ventoy2Disk/Ventoy2Disk
make -f Makefile.mingw

7. Configuration Mastery — ventoy.json

All Ventoy runtime configuration lives in a single JSON file at /ventoy/ventoy.json on the data partition (Partition 1). There is no formal schema documented in the source — the configuration structure is defined implicitly by the C code in Plugson and the GRUB2 modules that parse it.

Important

The ventoy.json file is optional. Ventoy works with zero configuration. Every configuration key described below is opt-in. Malformed JSON will cause Ventoy to silently ignore the entire configuration file and boot with defaults.

7.1 Configuration Categories

Based on source analysis of Plugson's JSON handling (ventoy_json.c) and GRUB2's config parsing, the major configuration sections are:

Boot control:

• Default boot image selection
• Boot timeout
• Menu display options (list mode vs. TreeView)
• GRUB theme selection
• Language/locale

Image filtering:

• Include/exclude patterns for image enumeration
• Directory-specific image ordering
• Image aliases (display names)
• Image tips (descriptions shown in menu)
• Image classes (icon mappings for GRUB themes)

Persistence:

• Persistence image mapping (link specific persistence files to specific ISOs)
• Persistence backends: raw image files, partition-based persistence
• Multiple persistence images per ISO (selectable at boot)

Auto-installation:

• Kickstart/preseed/autounattend file mapping
• Per-ISO auto-install configuration
• Injection of additional files/drivers into the boot environment

Plugin system:

• Password protection (plain, MD5, or SHA256 hash)
• Custom GRUB menu entries
• DUD (Driver Update Disk) injection
• Custom boot parameters (kernel command line appendix)
• Wimboot options for Windows images
• Secure Boot configuration overrides

7.2 Configuration Management via Plugson

Plugson provides a web UI for editing ventoy.json without manual JSON editing:

# Linux — launch Plugson for a specific USB device
sudo ./VentoyPlugson.sh /dev/sdb

# Opens browser to http://127.0.0.1:24681
# (port may vary; check terminal output)

On Windows, Plugson is accessible from the Ventoy2Disk GUI via a menu option.

The Plugson web interface provides:

• Form-based editing of each configuration section
• File browser for selecting ISOs and persistence images
• Validation of basic JSON structure before saving
• Preview of effective configuration

7.3 Theme Configuration

GRUB themes are placed in /ventoy/theme/ on the data partition:

/ventoy/
  theme/
    theme.txt          # GRUB theme definition
    background.png     # Background image
    icons/             # Boot entry icons
    fonts/             # Custom fonts (.pf2)

Theme selection in ventoy.json:

{
  "theme": {
    "file": "/ventoy/theme/theme.txt",
    "gfxmode": "1920x1080"
  }
}

7.4 Persistence Configuration

{
  "persistence": [
    {
      "image": "/ubuntu-22.04.iso",
      "backend": [
        "/persistence/ubuntu-rw.img"
      ]
    },
    {
      "image": "/kali-linux.iso",
      "backend": [
        "/persistence/kali-rw.img",
        "/persistence/kali-rw-backup.img"
      ]
    }
  ]
}

When multiple backends are listed for one image, Ventoy presents a selection menu at boot time. Persistence images are created using CreatePersistentImg.sh (Linux) or tools on the Ventoy website.

8. Distro Hook System

The distro hook system is the largest maintenance surface in Ventoy. It provides per-distribution compatibility patches that run during the boot initrd phase to ensure the target OS can find its root filesystem on the Ventoy-mapped virtual device.

8.1 Architecture

IMG/cpio/ventoy/
  hook/
    ventoy-hook-lib.sh      # Common library functions
    ventoy-os-lib.sh        # OS detection and dispatch
    alpine/                  # Alpine Linux hooks
    arch/                    # Arch Linux hooks
    debian/                  # Debian hooks
    fedora/                  # Fedora hooks
    gentoo/                  # Gentoo hooks
    manjaro/                 # Manjaro hooks
    nixos/                   # NixOS hooks
    suse/                    # openSUSE hooks
    ubuntu/                  # Ubuntu hooks
    ... (50+ additional distro directories)

8.2 Hook Mechanism

1. initrd injection — Ventoy prepends a custom cpio archive to the target ISO's initrd. This archive contains ventoy-hook-lib.sh, the appropriate distro hook script, and a udev rule.

2. udev rule (99-ventoy.rules) — Triggers when the block device subsystem initializes. Calls the Ventoy hook script.

3. Device-mapper setup — The hook script uses dmsetup to create /dev/mapper/ventoy, a device-mapper target that maps to the ISO content on the USB drive. This device-mapper target presents the ISO's filesystem as a standard block device.

4. Busybox — A minimal busybox binary is included in the injected cpio for environments where the target initrd lacks required utilities.

8.3 Hook Library Functions (ventoy-hook-lib.sh)

Key functions available to all distro hooks:

8.4 Special-Case Hooks

Some distributions require unique handling that goes beyond the standard device-mapper approach:

8.5 Precompiled Kernel Modules (vtloopex)

The vtloopex/ directory contains precompiled dm-mod.ko kernel modules for specific distro kernel versions. These are necessary for distributions that:

• Do not include device-mapper in their default initrd
• Ship minimal kernels without module loading support
• Use custom kernel configurations that exclude dm-mod

Each vtloopex entry is kernel-version-specific and must be updated when the target distro releases a new kernel.

Warning

The vtloopex precompiled modules are the most fragile part of the hook system. A kernel update in any supported distro can break boot compatibility until a matching dm-mod module is compiled and added. This is the primary reason some distro versions stop working after updates.

9. Security Model

9.1 UEFI Secure Boot

Ventoy implements Secure Boot support via the Machine Owner Key (MOK) mechanism:

1. First boot with Secure Boot enabled — UEFI firmware rejects Ventoy's unsigned bootloader
2. MOK enrollment — User must:
   • Boot with Secure Boot disabled (one time)
   • Or use MokManager to enroll ENROLL_THIS_KEY_IN_MOKMANAGER.cer from the VTOYEFI partition
3. Subsequent boots — The enrolled MOK key validates Ventoy's EFI binaries; Secure Boot proceeds normally

Caution

Enrolling the Ventoy MOK key trusts ALL binaries signed by that key. This is a machine-level trust decision. In enterprise environments, evaluate whether the Ventoy MOK key meets your organization's Secure Boot policy. Some organizations may require adding Ventoy's key to a centrally managed MOK database via mokutil.

Partition resize for Secure Boot:

# Adjust VTOYEFI partition for Secure Boot compatibility
sudo vtoycli partresize -s /dev/sdb

This modifies the VTOYEFI partition layout to accommodate Secure Boot shim and MOK binaries.

9.2 Password Protection

Ventoy supports password-protecting the boot menu via ventoy.json:

{
  "password": {
    "type": "sha256",
    "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }
}

Supported hash types: plain (cleartext — not recommended), md5, sha256.

The password protects access to the GRUB boot menu. It does not encrypt the USB drive contents — files on the exFAT data partition remain readable by any OS that mounts the drive.

9.3 dm-verity Integration

Boot hooks include veritysetup32 and veritysetup64 binaries for dm-verity support. This is used by specific distros (Chrome OS, Android-x86, and others) that require verified boot chains. Ventoy's hook system provides the verity setup tools when the target initrd expects them.

9.4 Binary Integrity and False Positives

Caution

Ventoy packages contain precompiled binaries (dmsetup, busybox, veritysetup, GRUB modules, EFI applications) that frequently trigger antivirus false positives. This is a known and recurring issue (GitHub issue #3569). The binaries are compiled from the source in this repository. VirusTotal reports should be evaluated in this context — heuristic detections on low-level boot utilities are expected behavior, not indicators of compromise.

9.5 Disk-Level Security Considerations

For environments requiring encrypted boot media, Ventoy is not a standalone solution. It must be combined with OS-level encryption (e.g., LUKS for Linux, BitLocker for Windows) applied to the booted OS, not to the Ventoy USB itself.

10. Deployment Strategies

10.1 Single USB — Interactive Use

The standard deployment: one USB drive, one user, interactive boot menu selection.

# Linux installation
sudo sh Ventoy2Disk.sh -i /dev/sdb

# With GPT partition table
sudo sh Ventoy2Disk.sh -i -g /dev/sdb

# Non-destructive install on existing NTFS drive
sudo sh Ventoy2Disk.sh -i -n /dev/sdb

# Custom partition label
sudo sh Ventoy2Disk.sh -i -L "MYBOOT" /dev/sdb

# Reserve 1GB at end of disk
sudo sh Ventoy2Disk.sh -i -r 1024 /dev/sdb

Warning

The -i (install) flag is destructive in normal mode — it wipes the entire disk. Double-check the target device with lsblk before running. The non-destructive (-n) flag preserves existing data by shrinking the filesystem.

10.2 Upgrade Existing Installation

# Upgrade Ventoy on USB (preserves data partition and all ISOs)
sudo sh Ventoy2Disk.sh -u /dev/sdb

Upgrades replace only the VTOYEFI partition contents and boot sector code. The data partition (Partition 1) is untouched — all ISO/WIM/VHD files are preserved.

10.3 Enterprise Mass Deployment

For deploying Ventoy to many USB drives:

#!/bin/bash
# Mass deployment script example
VENTOY_DIR="/path/to/ventoy-release"
ISO_SOURCE="/path/to/approved-images/"

for dev in /dev/sd{b,c,d,e,f}; do
  echo "Installing Ventoy to $dev"
  sudo "$VENTOY_DIR/Ventoy2Disk.sh" -i -g "$dev"
  
  # Wait for partition to appear
  sleep 2
  
  # Mount data partition and copy approved images
  mount_point=$(mktemp -d)
  mount "${dev}1" "$mount_point"
  cp -r "$ISO_SOURCE"/* "$mount_point/"
  
  # Copy standard configuration
  mkdir -p "$mount_point/ventoy"
  cp ventoy.json "$mount_point/ventoy/"
  
  umount "$mount_point"
  rmdir "$mount_point"
done

10.4 Ventoy Link Files (.vlnk)

For images stored on network shares or other partitions, Ventoy link files provide indirection:

# Create a .vlnk file pointing to a network-accessible image
# Linux
./VentoyVlnk.sh -c /path/to/actual.iso -o /ventoy-usb/link.vlnk

# Windows
VentoyVlnk.exe -c D:\images\actual.iso -o E:\link.vlnk

The .vlnk file is a small pointer file placed on the Ventoy data partition. At boot time, Ventoy resolves the link and boots the target image. This is useful when the actual ISO is too large for the USB or is maintained on a central file server.

Note

.vlnk files for GPT-partitioned drives have known issues (GitHub issue #3566). Test thoroughly in your environment before deploying.

10.5 LiveCD Deployment

The LiveCD/ and LiveCDGUI/ scripts generate a bootable ISO containing the Ventoy installer itself. This is useful for installing Ventoy on machines without an existing OS or USB boot capability — boot the LiveCD from optical media, then install Ventoy to a USB drive from within the live environment.

11. Operations and Maintenance

11.1 Version Upgrades

Important

Always upgrade via the official upgrade path (Ventoy2Disk.sh -u or Ventoy2Disk.exe Update button). Never manually modify the VTOYEFI partition. Manual changes will be overwritten on next upgrade and may leave the USB in an unbootable state.

Upgrade checklist:

1. Back up any custom ventoy.json and theme files from the data partition
2. Run the upgrade command
3. Verify boot on at least one test image
4. Restore custom configuration if overwritten (rare — upgrades typically preserve Partition 1)

11.2 Adding and Removing Boot Images

No special procedure required — copy files to or delete files from the Ventoy data partition using any file manager or command-line tool. Ventoy re-enumerates at every boot.

Supported file extensions: .iso, .wim, .img, .vhd, .vhdx, .efi, .vtoy, .vlnk

Subdirectory organization is supported — Ventoy scans recursively (or in TreeView mode, presents the directory structure as a navigable menu).

11.3 Monitoring USB Health

Ventoy does not include USB health monitoring. For drives used in production (kiosk boot, deployment stations), implement external monitoring:

# Check filesystem integrity
sudo fsck.exfat /dev/sdb1

# SMART data (if USB-to-SATA bridge supports it)
sudo smartctl -a /dev/sdb

# Monitor write cycles (USB flash has finite endurance)
# No built-in tool — use manufacturer utilities

11.4 Backup and Recovery

Warning

There is no built-in backup mechanism for Ventoy USB drives. The VTOYEFI partition can be recreated by re-running the installer, but custom configurations and theme files on Partition 1 require manual backup.

Recommended backup strategy:

1. Periodically copy /ventoy/ventoy.json and /ventoy/theme/ to a separate location
2. Maintain a master copy of all ISO images on a network share or NAS
3. Document the Ventoy version installed (check /ventoy/ventoy_version on VTOYEFI or the GRUB menu title)

11.5 Multi-Architecture USB Drives

A single Ventoy USB contains boot files for all supported architectures (i386 BIOS, x86_64 UEFI, ARM64 UEFI, MIPS64EL UEFI). The firmware selects the appropriate boot path automatically. No configuration is needed for multi-architecture support — it is the default.

However, the boot images themselves are architecture-specific. An x86_64 Linux ISO will not boot on ARM64 hardware. Organize images by architecture on the data partition for clarity:

/x86_64/
  ubuntu-22.04-amd64.iso
  windows-11.iso
/arm64/
  ubuntu-22.04-arm64.iso
  fedora-arm64.iso

12. Internationalization

12.1 Language System

The LANGUAGES/ directory contains two large JSON files (237KB total) with translations for the GRUB boot menu and installer UIs. Languages are loaded at runtime via vt_load_menu_lang in GRUB2.

To set the boot menu language, configure it in ventoy.json:

{
  "menu_lang": "zh_CN"
}

Or select the language interactively from the GRUB boot menu (F5 or language menu option, depending on theme).

12.2 Keyboard Layouts

The KBD/ directory contains keyboard layout configuration files. These are loaded by GRUB2 to support non-US keyboard layouts in the boot menu. Configure via:

{
  "menu_kbd": "de"
}

13. Troubleshooting Playbook

13.1 Boot Failures — Diagnostic Approach

USB not detected by firmware
  └─> Check BIOS boot order, enable USB boot
  └─> Try different USB port (USB 2.0 vs 3.0)
  └─> Verify Ventoy installation: mount VTOYEFI, check for grub/grub.cfg

GRUB menu appears but image won't boot
  └─> Check image integrity (MD5/SHA256 against source)
  └─> Try GRUB console: press 'c', run 'ls' to verify partitions
  └─> Check GRUB modules: ls (hd0,msdos2)/grub/x86_64-efi/

Image boots to black screen / kernel panic
  └─> Distro hook issue — check if distro is in supported list
  └─> Try adding 'nomodeset' to kernel parameters (press 'e' in GRUB, edit linux line)
  └─> Check vtloopex for kernel version mismatch

Windows setup error 0x80070001
  └─> Known issue with Windows 11 24H2 (GitHub #2887)
  └─> Try alternative WIM extraction method
  └─> Ensure USB is connected to USB 3.0 port for speed

13.2 Known Issue Reference

Caution

These are confirmed issues from the project's issue tracker. Workarounds are noted where available.

13.3 Secure Boot Enrollment Failures

Warning

If MOK enrollment fails or the certificate is rejected, the most common causes are:

1. Firmware bug — Some UEFI implementations have broken MokManager support. Try updating firmware.
2. Timeout — MOK enrollment has a short timeout window. Be ready to enter the password immediately.
3. Certificate format — The .cer file must be DER-encoded X.509. If it was accidentally converted, re-extract from a fresh Ventoy install.

Fallback: Disable Secure Boot in UEFI settings. This is acceptable for personal use but not for managed enterprise environments.

13.4 Filesystem Corruption Recovery

# exFAT data partition repair
sudo fsck.exfat -a /dev/sdb1

# Recreate VTOYEFI without touching data partition
sudo sh Ventoy2Disk.sh -u /dev/sdb

# Complete rebuild (destroys data partition)
sudo sh Ventoy2Disk.sh -i /dev/sdb

13.5 Debugging GRUB at Boot Time

Press c at the Ventoy GRUB menu to enter the GRUB command line:

grub> ls                          # List all detected drives/partitions
grub> ls (hd0,msdos1)/            # List files on data partition
grub> ls (hd0,msdos2)/grub/       # List GRUB directory on VTOYEFI
grub> cat (hd0,msdos2)/grub/grub.cfg  # View GRUB configuration
grub> set                         # Show all GRUB environment variables
grub> lsmod                       # List loaded GRUB modules

Press e on a menu entry to edit boot parameters before launching (add nomodeset, debug, break=init, etc.).

14. Platform Support Matrix

14.1 Host OS for Installation

14.2 Boot Target Firmware

14.3 Boot Target OS Families

15. Code Patterns and Conventions

15.1 Language and Style

The codebase is predominantly C (C89/C99) with POSIX shell scripts. There is no unified code style guide, but observed patterns include:

• C code: K&R-style braces, 4-space indentation in most modules, snake_case for functions, UPPER_CASE for macros and constants
• Shell scripts: #!/bin/sh (POSIX sh, not bash), extensive use of sed/awk/grep for text processing, set -e in installer scripts
• JSON: Machine-generated (language files) or hand-edited (ventoy.json) — no consistent formatting
• No formal testing framework: The project relies on manual testing across physical hardware and virtual machines

15.2 Naming Conventions

15.3 Error Handling Patterns

• C code: Return-code based (0 success, non-zero failure). No exception mechanism.
• Shell scripts: set -e for fail-fast; critical operations wrapped in conditionals with explicit error messages to stderr
• GRUB modules: Silent failure — most Ventoy GRUB commands fail gracefully by falling back to default behavior rather than halting boot
• Plugson: HTTP error responses (no structured error format)

15.4 Build Artifact Organization

Compiled binaries are placed in INSTALL/ alongside the shell installer scripts. The build system does not use a separate build/ or dist/ directory — output binaries go directly to their deployment location in the source tree.

This means INSTALL/ contains a mix of:

• Source (shell scripts)
• Compiled binaries (GRUB modules, EFI apps, tools)
• Boot images (cpio archives)
• Configuration files (grub.cfg)

15.5 Cross-Platform Abstractions

The codebase handles cross-platform differences at the source level:

• Disk access: PhyDrive.c (Windows CreateFile), Core/ventoy_disk.c (Linux /dev/sdX)
• GUI: Separate builds per toolkit (GTK2, GTK3, QT5, WebUI) with shared core logic
• Filesystem: Embedded FatFs (Windows installer) vs. OS-level mount (Linux installer)
• Compilation: Separate Makefiles per target (MinGW for Windows cross-compile, native gcc for Linux)

16. Developer Internals

16.1 Adding Support for a New Distribution

To add boot support for a new Linux distribution:

1. Identify the initrd format — Is it cpio, cpio.gz, cpio.xz, or something custom?
2. Determine root-finding mechanism — How does the distro's init/systemd locate its root filesystem?
3. Create a hook script in IMG/cpio/ventoy/hook/{distro_name}/:

#!/bin/sh
# ventoy-hook.sh for NewDistro
. /ventoy/hook/ventoy-hook-lib.sh

ventoy_udev_disk_common

4. Test device-mapper availability — If the distro's initrd includes dmsetup, the standard hook works. If not, compile dm-mod.ko for the distro's kernel version and add to vtloopex/.
5. Add udev rule if the distro uses a non-standard udev path
6. Test: Boot the ISO in both Legacy BIOS and UEFI modes on real hardware (VMs may mask firmware-specific issues)
7. Rebuild initrd cpio — The IMG build process repackages all hooks into the boot cpio archives

16.2 Modifying GRUB2 Ventoy Commands

Ventoy-specific GRUB commands live in GRUB2/MOD_SRC/grub-2.04/grub-core/ventoy/:

1. Modify or add command handlers in the ventoy/ subdirectory
2. Register new commands in the GRUB module initialization
3. Rebuild GRUB for all four target architectures
4. Test boot with verbose GRUB output (set debug=all in grub.cfg)

16.3 Modifying the EDK2 UEFI Application

1. Source is in EDK2/edk2_mod/
2. The build uses EDK2's own build system (not Make directly)
3. Modify VDiskChain or VtoyUtil protocol handlers
4. Build with: build -a X64 -t GCC5 -p VentoyPkg/VentoyPkg.dsc
5. Test in QEMU with OVMF firmware before physical hardware

16.4 The VentoyWorker.sh Installation Logic

VentoyWorker.sh (in INSTALL/) contains the core installation logic:

• Partition creation: Calculates sizes based on disk capacity, creates MBR/GPT, formats Partition 1 (exFAT) and Partition 2 (FAT16)
• Cluster size selection: 128KB for disks >32GB, 32KB for ≤32GB (optimized for large sequential reads of ISO files)
• VENTOY_SECTOR_NUM constant: Defines the exact size of the VTOYEFI partition (32MB equivalent in sectors)
• Boot sector installation: Writes MBR boot code or GPT protective MBR + EFI boot entries
• Non-destructive mode: Uses ntfsresize (NTFS) or resize2fs (ext2/3/4) to shrink existing filesystems

16.5 Extending Plugson

To add a new configuration section to Plugson:

1. Add JSON parsing logic in Plugson/src/ventoy_json.c
2. Create the web UI page in Plugson/www/ (AdminLTE template structure)
3. Add API endpoint in the civetweb handler registration
4. Rebuild Plugson (cd Plugson/src && make)

17. Performance Considerations

17.1 Boot Speed Factors

17.2 Filesystem Choice Impact

18. Testing Strategy

The project has no automated test suite. Testing is performed manually across a matrix of:

• Firmware: Legacy BIOS, UEFI with Secure Boot off, UEFI with Secure Boot on
• Hardware: Multiple USB controller types (EHCI, XHCI), multiple UEFI implementations (AMI, Phoenix, Insyde, TianoCore)
• Virtual machines: QEMU/KVM (with OVMF for UEFI), VirtualBox, VMware
• Distributions: Regression testing across the 900+ supported distros (subset-based)

For contributors, the minimum test matrix should cover:

1. One Legacy BIOS boot (any Linux ISO)
2. One UEFI boot (any Linux ISO)
3. One Windows WIM boot (Windows 10/11 installer ISO)
4. One VHD boot (Windows VHD)
5. The specific distro/feature being modified

19. Improvement Opportunities

19.1 Architecture

• GRUB2 upstream rebase — Ventoy is pinned to GRUB 2.04 (released 2019). Upstream GRUB has had security fixes and feature improvements. The Ventoy modifications are extensive enough that rebasing is a multi-week effort, but the security exposure grows with time.
• EDK2 upstream rebase — Pinned to edk2-stable201911 (2019). Same concern as GRUB2.
• iPXE upstream rebase — Pinned to commit 3fe683e. Less critical than GRUB2/EDK2 as iPXE is a secondary boot path.

19.2 Build System

• No parallel component builds — Each component builds sequentially. Independent components (GRUB2 architectures, utilities) could build in parallel.
• No incremental builds — Changes to one module require a full rebuild cycle.
• No CI/CD pipeline — The Docker CI script exists but is not integrated with GitHub Actions or any CI service.

19.3 Code Quality

• No automated testing — The entire test strategy is manual. Unit tests for the C utilities (vtoycli, vtoygpt, vtoyfat) would catch regressions.
• No static analysis — No Coverity, cppcheck, or clang-tidy integration.
• Mixed binary/source in INSTALL/ — Compiled artifacts committed alongside source makes the repository large and git history opaque.

19.4 Documentation

• No formal schema for ventoy.json — Configuration is defined implicitly by the C parser. A JSON Schema would enable validation tooling.
• No developer onboarding guide — The repository has no README, no CONTRIBUTING.md, no architecture documentation. This Admin Guide serves as the first comprehensive reference.
• Hook system undocumented — The per-distro hook mechanism is learned by reading existing hooks. A hook development guide would lower the contribution barrier.

19.5 Security

• No reproducible builds — The Docker CI script improves consistency but does not guarantee bit-for-bit reproducibility.
• Precompiled binaries in repo — The dmsetup, busybox, and veritysetup binaries are committed pre-built. Building from source and documenting the exact toolchain would improve trust.
• MOK key management — The same MOK key is used across all Ventoy installations. A compromised key would affect all users. Per-installation key generation would be more secure but dramatically less user-friendly.

20. Quick Reference

20.1 Installation Commands

# Install (destructive)
sudo sh Ventoy2Disk.sh -i /dev/sdX

# Install with GPT
sudo sh Ventoy2Disk.sh -i -g /dev/sdX

# Non-destructive install
sudo sh Ventoy2Disk.sh -i -n /dev/sdX

# Upgrade (preserves data)
sudo sh Ventoy2Disk.sh -u /dev/sdX

# Custom label + reserved space
sudo sh Ventoy2Disk.sh -i -L "MYBOOT" -r 1024 /dev/sdX

# Secure Boot partition resize
sudo vtoycli partresize -s /dev/sdX

# Launch Plugson
sudo ./VentoyPlugson.sh /dev/sdX

# Create Ventoy link file
./VentoyVlnk.sh -c /path/to/image.iso -o /ventoy-usb/link.vlnk

20.2 Key File Locations

20.3 Supported Image Formats

20.4 GRUB Boot Menu Hotkeys