# Variable Expansion Syntax for Ventoy Auto-Installation Scripts: A Complete Guide

> Master Ventoy variable expansion syntax $$VT_VARIABLE_NAME$$ for auto-installation scripts. Dynamically insert disk names sizes and system values with this complete guide.

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

---

**Ventoy auto-installation scripts use the syntax `$$VT_VARIABLE_NAME$$` where the variable name is enclosed in double dollar signs, processed by the `vtoyexpand` binary during boot to dynamically insert disk names, sizes, and other system values.**

Ventoy's auto-install feature allows you to automate OS deployments by providing plain-text configuration files that adapt to the target hardware at boot time. According to the `ventoy/Ventoy` source code, this dynamic behavior is achieved through a specialized variable expansion system that replaces placeholders with computed values based on the current system's disk topology.

## Ventoy Variable Expansion Syntax

The fundamental syntax for variable expansion follows a strict double-dollar notation:

```

$$VT_VARIABLE_NAME$$

```

This pattern must begin with `$$VT_` and end with `$$`. The variable name between these delimiters determines what value gets substituted during the boot process. For example, `$$VT_LINUX_DISK_MAX_SIZE$$` would be replaced with the device name of the largest disk detected on the system.

## How Variable Expansion Works in Ventoy

The expansion process involves two core components in the Ventoy source tree: a shell script that detects placeholders and a C binary that performs the actual substitution.

### Detection Phase

The script [`IMG/cpio/ventoy/hook/default/auto_install_varexp.sh`](https://github.com/ventoy/Ventoy/blob/main/IMG/cpio/ventoy/hook/default/auto_install_varexp.sh) scans the autoinstall file for any placeholder containing the substring `$$VT_`. If detected, it triggers the expansion workflow:

```bash
if grep -q '\$\$VT_' /ventoy/autoinstall; then
    vlog "======== auto install variables expansion ======="
    vtoyexpand "$1" "$VTOYDISK"
fi

```

This check occurs early in the boot process to determine whether variable processing is required before the installation begins.

### Parsing and Replacement

When placeholders are detected, the script invokes the `vtoyexpand` binary (compiled from [`VtoyTool/vtoyexpand.c`](https://github.com/ventoy/Ventoy/blob/main/VtoyTool/vtoyexpand.c)). The binary processes the autoinstall file line by line, identifying delimiters using `strstr`:

```c
start = strstr(line, "$$VT_");          // find opening delimiter
end   = strstr(start + 5, "$$");       // find closing delimiter

if (start && end) {
    *start = 0;                     // write part before placeholder
    fprintf(fout, "%s", line);
    *end = 0;                       // isolate placeholder name
    expand_var(start + 2, value, sizeof(value));
    fprintf(fout, "%s", value);     // write expanded value
    fprintf(fout, "%s", end + 2);   // write rest of line
}

```

The `expand_var()` function in [`vtoyexpand.c`](https://github.com/ventoy/Ventoy/blob/main/vtoyexpand.c) (lines 456-511) contains the logic for mapping variable names to their computed values.

## Supported Variables for Auto-Installation

The Ventoy source code defines a fixed set of variable names in the `expand_var()` function. These variables enable dynamic disk selection without hardcoding device names:

- **VT_LINUX_DISK_SDX_1ST_NONVTOY** – Resolves to the first SD-X style device (e.g., `sda`, `sdb`) that is not the Ventoy boot device
- **VT_LINUX_DISK_SDX_1ST_NONUSB** – Resolves to the first SD-X device that is not attached via USB
- **VT_LINUX_DISK_MAX_SIZE** – Resolves to the device name with the largest storage capacity
- **VT_LINUX_DISK_CLOSEST_<GB>** – Resolves to the disk whose size is closest to the specified `<GB>` value (e.g., `$$VT_LINUX_DISK_CLOSEST_100$$` finds the disk nearest to 100 GiB)

If a placeholder does not match any known variable in the source code, Ventoy leaves it unchanged in the output file.

## Practical Examples

### Basic Syntax in Kickstart Files

When creating an unattended installation for Red Hat-based systems, you can embed Ventoy variables directly in the kickstart file:

```text

# Autoinstall configuration for Rocky Linux

install
url --url="http://mirror.example.com/rocky/9/BaseOS/x86_64/os/"
autopart --type=lvm

%pre

# Dynamically select the largest available disk

DISK="$$VT_LINUX_DISK_MAX_SIZE$$"
echo "Selected disk: $DISK"
%end

```

At boot time, Ventoy replaces `$$VT_LINUX_DISK_MAX_SIZE$$` with the actual device node (e.g., `sda` or `nvme0n1`) before the installer reads the file.

### Selecting Non-USB Disks

For installations where you must avoid USB drives (common when the Ventoy media itself is USB), use the NONUSB variable:

```text
part / --fstype=ext4 --onpart=$$VT_LINUX_DISK_SDX_1ST_NONUSB$$1

```

This ensures the installation targets the first internal SATA or NVMe disk rather than any USB storage device present during installation.

## Extending Variable Expansion

While Ventoy ships with predefined variables, the source architecture allows for extension. To add a custom variable, you would modify the `expand_var()` function in [`VtoyTool/vtoyexpand.c`](https://github.com/ventoy/Ventoy/blob/main/VtoyTool/vtoyexpand.c):

```c
else if (strcmp(var, "VT_CUSTOM_HOSTNAME") == 0) {
    snprintf(value, len, "auto-host-%s", get_disk_serial());
    return 0;
}

```

After recompiling `vtoyexpand` and rebuilding the Ventoy image, your autoinstall files could use `$$VT_CUSTOM_HOSTNAME$$` to insert dynamically generated hostnames based on hardware identifiers.

## Summary

- **Syntax**: Use `$$VT_VARIABLE_NAME$$` with double dollar signs as opening and closing delimiters
- **Detection**: The [`auto_install_varexp.sh`](https://github.com/ventoy/Ventoy/blob/main/auto_install_varexp.sh) script scans for `$$VT_` patterns before installation begins
- **Processing**: The `vtoyexpand` binary performs actual substitution by parsing [`VtoyTool/vtoyexpand.c`](https://github.com/ventoy/Ventoy/blob/main/VtoyTool/vtoyexpand.c)
- **Available variables**: Include disk selection helpers like `VT_LINUX_DISK_MAX_SIZE` and `VT_LINUX_DISK_SDX_1ST_NONVTOY`
- **Fallback behavior**: Unknown variables remain unchanged in the output file
- **Extensibility**: New variables can be added by extending the `expand_var()` function in the source code

## Frequently Asked Questions

### What is the exact syntax for Ventoy auto-installation variables?

The exact syntax is `$$VT_VARIABLE_NAME$$` where `VARIABLE_NAME` is replaced with one of the supported identifiers defined in the Ventoy source code. Both the opening `$$VT_` and closing `$$` are required for the `vtoyexpand` binary to recognize and process the placeholder.

### Which file handles the variable expansion in Ventoy?

Variable expansion is handled by two files in the `ventoy/Ventoy` repository: [`IMG/cpio/ventoy/hook/default/auto_install_varexp.sh`](https://github.com/ventoy/Ventoy/blob/main/IMG/cpio/ventoy/hook/default/auto_install_varexp.sh) detects placeholders and triggers processing, while [`VtoyTool/vtoyexpand.c`](https://github.com/ventoy/Ventoy/blob/main/VtoyTool/vtoyexpand.c) contains the actual implementation including the `expand_var()` function that maps variable names to system values.

### Can I use custom variables in Ventoy auto-install scripts?

Yes, but it requires modifying the source code. You must add a new case in the `expand_var()` function within [`VtoyTool/vtoyexpand.c`](https://github.com/ventoy/Ventoy/blob/main/VtoyTool/vtoyexpand.c), recompile the `vtoyexpand` binary, and rebuild the Ventoy image. Without source modification, only the built-in variables are recognized.

### What happens if I use an unrecognized variable name?

If the variable name between the delimiters does not match any case in the `expand_var()` function, Ventoy leaves the placeholder unchanged in the autoinstall file. For example, `$$VT_UNKNOWN_VAR$$` would remain as literal text in the output rather than being replaced with a value.