# Creating and Mounting a Linux persistence.dat File for Ventoy: Complete Technical Guide

> Learn to create and mount a Linux persistence.dat file for Ventoy using the CreatePersistentImg.sh script. Enable automatic mounting for your live Linux USB.

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

---

**Creating a Linux persistence.dat file for Ventoy requires generating a non-sparse disk image with an ext4 filesystem labeled `casper-rw` using the [`CreatePersistentImg.sh`](https://github.com/ventoy/Ventoy/blob/main/CreatePersistentImg.sh) script, placing it on the USB drive, and configuring the path through Ventoy's web UI so the live system mounts it automatically during boot.**

Ventoy's persistence plugin enables Linux live distributions to retain user data and system modifications across reboots by utilizing a writable disk image file. This guide details the complete process of creating and mounting a Linux persistence.dat file for Ventoy, referencing the actual implementation in the `ventoy/Ventoy` repository source code. Understanding these technical requirements ensures your persistent storage functions correctly with Ubuntu, Debian, and other supported distributions.

## Understanding Ventoy Persistence Requirements

Before creating the file, you must understand the specific technical requirements Ventoy enforces for persistence images. These specifications are hard-coded into the Ventoy source and validated during the boot process.

### File Naming and Location Conventions

Ventoy accepts two naming patterns for persistence files. The system first looks for a distribution-specific file named `<os_name>_persistence.dat` (for example, `ubuntu_persistence.dat` or `debian_persistence.dat`). Alternatively, if you place a file named exactly `persistence.dat` at the root of the USB drive, Ventoy recognizes it as a generic persistence image. According to the UI strings in [`Plugson/www/plugson_persistence.html`](https://github.com/ventoy/Ventoy/blob/main/Plugson/www/plugson_persistence.html), valid paths include both Windows-style (`\ventoy\ubuntu_persistence.dat`) and Linux-style (`/ventoy/ubuntu_persistence.dat`) syntax, though the path is stored verbatim in the configuration.

### Filesystem and Label Specifications

The disk image must contain a valid **ext2**, **ext3**, **ext4**, or **xfs** filesystem. The filesystem label is critical: it defaults to `casper-rw`, which matches the default expectation of Ubuntu and Debian live systems. You can specify a custom label using the `-l` option when creating the image, but you must ensure the boot parameters match this label exactly. The filesystem creation logic resides in [`CreatePersistentImg.sh`](https://github.com/ventoy/Ventoy/blob/main/CreatePersistentImg.sh), which invokes `mkfs` with the appropriate label flag.

### Optional Configuration and Encryption

For distributions that require explicit persistence configuration, you can embed a configuration file (default name [`persistence.conf`](https://github.com/ventoy/Ventoy/blob/main/persistence.conf)) inside the image containing the line `/ union`. This is enabled via the `-c` option in the creation script. Additionally, **LUKS encryption** is supported for select distributions using the `-e` flag, which invokes `cryptsetup` during image creation. However, encryption only functions if the target distribution's initramfs includes the necessary cryptsetup hooks to unlock the device during boot.

## Creating a Linux persistence.dat File Using Official Scripts

Ventoy provides two Bash helper scripts in the `INSTALL` directory to manage persistence images without manual partitioning.

### Using CreatePersistentImg.sh

The [`CreatePersistentImg.sh`](https://github.com/ventoy/Ventoy/blob/main/CreatePersistentImg.sh) script generates a fresh, non-sparse file with a formatted filesystem. This script is located at [`INSTALL/CreatePersistentImg.sh`](https://github.com/ventoy/Ventoy/blob/main/INSTALL/CreatePersistentImg.sh) in the Ventoy repository. The script forces a **non-sparse** file by piping `dd` output through `tr '\000' '\377'` to fill the entire allocated space with `0xFF` bytes. This is essential because sparse files would break the loop-device mount that Ventoy performs during boot.

The script accepts the following key parameters:

- **`-s <size-MB>`**: Specifies the image size in megabytes (default 1024). Minimum requirements vary by filesystem: xfs requires at least 16 MB, while ext filesystems require at least 1 MB.
- **`-t <fstype>`**: Selects the filesystem type (`ext4`, `ext2`, `ext3`, or `xfs`).
- **`-l <label>`**: Sets the filesystem label (default `casper-rw`).
- **`-c <config-file>`**: Copies a configuration file into the image (typically containing `/ union`).
- **`-o <output-file>`**: Names the output file (default `persistence.dat`).
- **`-e`**: Enables LUKS encryption (requires `cryptsetup`).

To create a 4 GB ext4 persistence file for Ubuntu:

```bash
sudo ./CreatePersistentImg.sh -s 4096 -t ext4 -l casper-rw -c persistence.conf -o ubuntu_persistence.dat

```

### Extending Existing Images with ExtendPersistentImg.sh

If you need to resize an existing persistence file without losing data, use [`INSTALL/ExtendPersistentImg.sh`](https://github.com/ventoy/Ventoy/blob/main/INSTALL/ExtendPersistentImg.sh). This script grows or shrinks the file while preserving the underlying filesystem structure. You specify the target size in MB, which can be negative to shrink the image, though shrinking requires sufficient free space within the filesystem.

```bash
sudo ./ExtendPersistentImg.sh ubuntu_persistence.dat 8192

```

## Manually Mounting and Verifying a persistence.dat File

For troubleshooting or data recovery, you can manually mount the persistence file on a Linux host to verify its contents or label. Ventoy itself does not use these commands during boot—it passes the file directly to the kernel as a block device—but manual mounting validates that the image was created correctly.

First, associate the file with a loop device:

```bash
LOOP=$(losetup -f --show ubuntu_persistence.dat)

```

Verify the filesystem label matches expectations:

```bash
sudo blkid ${LOOP}

# Expected output: LABEL="casper-rw"

```

Mount the filesystem read-write to inspect or modify contents:

```bash
sudo mkdir -p /mnt/persist
sudo mount ${LOOP} /mnt/persist
df -h /mnt/persist

```

When finished, unmount and detach the loop device:

```bash
sudo umount /mnt/persist
sudo losetup -d ${LOOP}

```

## Ventoy Persistence Plugin Architecture

Understanding the internal data flow helps diagnose configuration issues. The persistence plugin implementation spans multiple source files in the `Plugson` directory.

### Core Data Structures and API Functions

The file [`Plugson/src/Web/ventoy_http.h`](https://github.com/ventoy/Ventoy/blob/main/Plugson/src/Web/ventoy_http.h) defines the `plugin_type_persistence` constant and the `persistence_node` structure, which forms a linked list stored in `g_data_persistence[bios_max+1]`. Each node contains the file path, label, and optional configuration data.

In [`Plugson/src/Web/ventoy_http.c`](https://github.com/ventoy/Ventoy/blob/main/Plugson/src/Web/ventoy_http.c), several functions manage persistence state:

- **`ventoy_data_default_persistence()`**: Initializes and clears the persistence node list.
- **`ventoy_data_save_persistence()`**: Serializes the linked list into Ventoy's internal JSON format, storing the path exactly as specified in the web UI.
- **`ventoy_api_get_persistence()`**: Exposes current persistence entries to the web interface.
- **`ventoy_api_save_persistence()`**: Receives JSON payloads from the web UI, updates the `persistence_node` list, and writes the configuration to [`ventoy.json`](https://github.com/ventoy/Ventoy/blob/main/ventoy.json).

### Web UI Configuration Flow

The file [`Plugson/www/plugson_persistence.html`](https://github.com/ventoy/Ventoy/blob/main/Plugson/www/plugson_persistence.html) renders the persistence management interface. When you add a persistence entry through the web UI, the path is captured (supporting both Windows and Linux path syntaxes) and passed to `ventoy_api_save_persistence()`. At the next boot, Ventoy reads [`ventoy.json`](https://github.com/ventoy/Ventoy/blob/main/ventoy.json), constructs the appropriate kernel command line parameters (`persistent`, `persistent-path=...`, `persistent-label=...`), and appends them to the live OS boot options. The live system's initramfs then locates the file by label and mounts it as the writable layer (typically at `/cow` for Ubuntu-based systems).

## Critical Considerations for Ventoy Persistence

Several technical constraints can cause persistence to fail silently if ignored. The Ventoy source code enforces these requirements strictly.

**Filesystem Compatibility**: Not all distributions support xfs persistence. Ubuntu and Debian expect ext2/3/4 with the `casper-rw` label. Using xfs without explicit distro support results in a read-only live environment.

**Non-Sparse File Requirement**: The image must be a fully allocated, non-sparse file. The [`CreatePersistentImg.sh`](https://github.com/ventoy/Ventoy/blob/main/CreatePersistentImg.sh) script enforces this by writing `0xFF` bytes across the entire file size. Sparse files appear smaller to the kernel and break loop-mounting during boot.

**Size Alignment**: Ventoy expects the image size to be an exact multiple of 1 MiB. The script handles this alignment automatically when you use the `-s` parameter. Manual creation with `dd` must respect this alignment constraint.

**Label Mismatch Risks**: If the kernel boot parameters specify a label that differs from the actual filesystem label created with `-l`, the live system will fail to locate the persistence device and boot without write support. Always verify with `blkid` before deployment.

**Multi-Distro USBs**: When running multiple Linux distributions from one USB drive, you must either use separate files (`ubuntu_persistence.dat`, `debian_persistence.dat`) or ensure all distros share the same persistence label and configuration. The web UI allows configuring separate paths for each ISO.

**Encryption Limitations**: LUKS-encrypted persistence (enabled with `-e`) requires that the target distribution's initramfs includes `cryptsetup` and knows how to prompt for the passphrase during early boot. Only specific distributions support this workflow.

## Complete Workflow: From Creation to Boot

Follow this verified sequence to deploy persistence on your Ventoy USB drive:

1. **Prepare the USB device** by installing Ventoy using the official installer, ensuring the partition table is correct for your boot mode (MBR or GPT).

2. **Generate the persistence image** using the official script with appropriate size and label:

   ```bash
   sudo ./CreatePersistentImg.sh -s 4096 -t ext4 -l casper-rw -o ubuntu_persistence.dat
   ```

3. **Copy the file to the USB** in either the root directory or the `ventoy/` subdirectory:

   ```bash
   sudo cp ubuntu_persistence.dat /media/username/Ventoy/ventoy/
   ```

4. **Configure via Web UI**: Boot any computer from the Ventoy USB, press `F2` (or access the Plugson interface), navigate to the **Persistence** tab, and add the path `/ventoy/ubuntu_persistence.dat` to the appropriate ISO entry.

5. **Save configuration**: Click Save in the web UI. This invokes `ventoy_api_save_persistence()` in [`ventoy_http.c`](https://github.com/ventoy/Ventoy/blob/main/ventoy_http.c) to write the updated [`ventoy.json`](https://github.com/ventoy/Ventoy/blob/main/ventoy.json) file.

6. **Boot the target system**: Select your Linux ISO from the Ventoy menu. The kernel will receive the `persistent` parameter and automatically mount the file as the writable overlay.

7. **Verify operation**: Once booted, run `mount | grep casper` to confirm a mount point like `/cow` exists, indicating the persistence layer is active.

## Summary

- **Use [`CreatePersistentImg.sh`](https://github.com/ventoy/Ventoy/blob/main/CreatePersistentImg.sh)** to generate non-sparse persistence images with proper alignment and filesystem labels.
- **Ensure the label matches** the default `casper-rw` or your custom boot parameter configuration.
- **Place the file** at the USB root as `persistence.dat` or in the `ventoy/` folder as `<distro>_persistence.dat`.
- **Configure paths** through the Ventoy web UI, which stores data via `ventoy_data_save_persistence()` in [`ventoy.json`](https://github.com/ventoy/Ventoy/blob/main/ventoy.json).
- **Avoid sparse files** and ensure size multiples of 1 MiB to prevent loop-mount failures.
- **Verify manually** using `losetup` and `mount` before deployment to confirm filesystem integrity.

## Frequently Asked Questions

### Can I use the same persistence.dat file for multiple Linux distributions on one USB?

You can share a persistence file only if all distributions use the same persistence label (default `casper-rw`) and compatible filesystem types. However, **separate files are recommended** (e.g., `ubuntu_persistence.dat` and `debian_persistence.dat`) to avoid configuration conflicts. The Ventoy web UI in [`plugson_persistence.html`](https://github.com/ventoy/Ventoy/blob/main/plugson_persistence.html) allows you to map specific files to specific ISOs in the [`ventoy.json`](https://github.com/ventoy/Ventoy/blob/main/ventoy.json) configuration.

### What happens if I create a sparse persistence image instead of a non-sparse one?

Ventoy requires a fully allocated, non-sparse file because the kernel treats the image as a raw block device. **Sparse files break the loop-mount mechanism** and cause the live system to boot without persistence enabled. The official [`CreatePersistentImg.sh`](https://github.com/ventoy/Ventoy/blob/main/CreatePersistentImg.sh) script prevents this by writing `0xFF` bytes across the entire file using `tr '\000' '\377'`, ensuring the file occupies its full declared size on disk.

### How do I resize an existing Ventoy persistence file without losing data?

Use the [`ExtendPersistentImg.sh`](https://github.com/ventoy/Ventoy/blob/main/ExtendPersistentImg.sh) script provided in the `INSTALL` directory. This utility safely expands or shrinks the file while preserving the existing filesystem. Specify the new size in MB as the second argument; for example, `sudo ./ExtendPersistentImg.sh persistence.dat 2048` grows the file to 2 GB. The script handles the underlying filesystem resize operations automatically.

### Is LUKS encryption supported for Ventoy persistence files?

Yes, but with limitations. You can create an encrypted persistence image using the `-e` flag in [`CreatePersistentImg.sh`](https://github.com/ventoy/Ventoy/blob/main/CreatePersistentImg.sh), which invokes `cryptsetup` to encrypt the container. However, **only specific distributions** (such as Ubuntu with full disk encryption support in the initramfs) can unlock the device during boot. Ventoy passes the encrypted block device to the kernel, but the live OS must handle the decryption prompt and mounting logic.