Home · Persistence guide

Ventoy persistence for Linux live USB

Persistence stores packages, Wi-Fi profiles, and files across reboots of a supported Linux live ISO. Windows installer ISOs do not use this mechanism. If your distro’s live session has no persistence boot entry, mapping a file in Ventoy will not invent one.

Independent guide on ventoy.io. Plugin file names and JSON keys follow the Ventoy plugin documentation for your exact version—check that document if a new release renamed a field.

What you need

• A Linux ISO that documents persistence (Ubuntu-family live images are the usual starting point).
• Free space on the Ventoy data partition for both the ISO and the persistence image.
• A ventoy/ventoy.json file on that same data partition (not on the EFI partition).

Build steps

1. Create a persistence image with a size you can actually fill. Four to eight GB is a common lab default; larger files take longer to create and wear the flash more.
2. Copy the ISO and the persistence file onto the large Ventoy partition. Keep names simple (hyphens, no spaces) if you edit JSON by hand.
3. Map the ISO path to the persistence file in plugin JSON. The path must match the real location, including folders. Linux filesystems treat Ubuntu.iso and ubuntu.iso as different files.
4. Validate JSON (missing commas are the usual failure) before you unplug the stick.
5. Boot the ISO, select the persistence option, create a small marker file on the desktop, reboot, and confirm the marker is still there.

Troubleshooting

• No persistence menu entry: the ISO may not support it, or you booted a different file than the one in JSON.
• Entry appears, changes vanish: the session started without persistence (wrong boot line) or the image file is corrupted. Recreate the persistence file and test with a distro you already know works.
• JSON ignored: file must live at ventoy/ventoy.json on the data partition. A copy on the EFI volume is not read as plugin config.
• Works in a VM, not on a laptop: confirm UEFI vs BIOS for that ISO, then retry USB 2.0. Persistence bugs are often “wrong boot mode” in disguise.

Limits

Persistence is not a backup. USB flash fails. Keep copies of ventoy.json and any overlay you care about on another disk. Do not point two different ISOs at one persistence file unless the plugin docs for your version say that is supported.