Ludusavi Ludusavi
Ludusavi is a tool for backing up your PC video game save data, written in Rust. It is cross-platform and supports multiple game stores.
This tool uses the Ludusavi Manifest for info on what to back up, and it will automatically download the latest version of the primary manifest. To add or update game entries in the primary manifest, please refer to that project. Data is ultimately sourced from PCGamingWiki, so you are encouraged to contribute any new or fixed data back to the wiki itself.
Ludusavi is available for Windows, Linux, and Mac. However, your computer must support one of these graphics systems: Vulkan, DirectX (11 or 12), or Metal. (Experimental builds with OpenGL support are also available - give them a try if the standard builds don't work on your system.)
You can install Ludusavi one of these ways:
Download the executable for your operating system from the releases page. It's portable, so you can simply download it and put it anywhere on your system. If you're unsure, choose this option.
On Windows, you can use Scoop. To install, run:
scoop bucket add extras
scoop install ludusavi
To update, run:
scoop update
scoop update ludusavi
If you have Rust, you can use Cargo. To install or update, run:
cargo install ludusavi
On Linux, this requires the following system packages, or their equivalents for your distribution:
sudo apt-get install -y gcc cmake libx11-dev libxcb-composite0-dev libfreetype6-dev libexpat1-dev libfontconfig1-devIf you are on Windows:
If you are on Mac:
How to open an app [...] from an unidentified developer.preview to see what the backup will include,
without actually performing it.back up to perform the backup for real.
Celeste would go into a folder named Q2VsZXN0ZQ==.D:/Steam/steamapps/common/Celeste/Saves/0.celeste would be
backed up as RDovU3RlYW0vc3RlYW1hcHBzL2NvbW1vbi9DZWxlc3RlL1NhdmVzLzAuY2VsZXN0ZQ==.other/registry.yaml file.
If you are using Steam and Proton instead of Windows, then the Proton *.reg
files will be backed up like other game files.add root to configure
as many as you need, along with the root's type:
steamapps and
userdata subdirectories. Here are some common/standard locations:C:/Program Files (x86)/Steam~/.steam/steamD:/Epic and it creates a subfolder for D:/Epic/Celeste, then the root
would be D:/Epic).deselect all button
(when all games are selected) or the select all button (when at least
one game is deselected) to quickly toggle all of them at once.
Ludusavi will remember your most recent checkbox settings.restore mode button.preview to see what the restore will include,
without actually performing it.restore to perform the restore for real.
You can use redirects to restore to a different location than the original file.
Click add redirect, and then enter both the old and new location. For example,
if you backed up some saves from C:/Games, but then you moved it to D:/Games,
then you would put C:/Games as the source and D:/Games as the target.
Tip: As you're editing your redirects, try running a preview and expanding some games' file lists. This will show you in real time what effect your redirects will have when you perform the restore for real.
custom games button.add game to add entries for as many games as you like.
Within each game's entry, you can click the plus icons to add paths
(files or directories) and registry keys.
C:/example/*.txt selects all TXT files in that folder)
and the placeholders defined in the
Ludusavi Manifest format.Make sure to give the game entry a name. Entries without names are ignored, as are empty paths and empty registry keys.
If the game name matches one from Ludusavi's primary data set, then your custom entry will override it.
Run ludusavi --help for the full usage information.
CLI mode defaults to a human-readable format, but you can switch to a
machine-readable JSON format with the --api flag. In that case, the output
will have the following structure:
errors (optional, map):
someGamesFailed (optional, boolean): Whether any games failed.unknownGames (optional, list of strings): Names of unknown games, if any.overall (map):
totalGames (number): How many games were found.totalBytes (number): How many bytes are used by files associated with
found games.processedGames (number): How many games were processed.
This excludes ignored, failed, and cancelled games.processedBytes (number): How many bytes were processed.
This excludes ignored, failed, and cancelled games.games (map):
decision (string): How Ludusavi decided to handle this game.
Possible values:
ProcessedIgnoredCancelledfiles (map):
failed (optional, boolean): Whether this entry failed to process.bytes (number): Size of the file.originalPath (optional, string): If the file was restored to a
redirected location, then this is its original path.registry (map):
failed (optional, boolean): Whether this entry failed to process.Note that, in some error conditions, there may not be any JSON output, so you should check if stdout was blank before trying to parse it.
Example:
json
{
"errors": {
"someGamesFailed": true,
},
"overall": {
"totalGames": 2,
"totalBytes": 150,
"processedGames": 1,
"processedBytes": 100,
},
"games": {
"Game 1": {
"decision": "Processed",
"files": {
"/games/game1/save.json": {
"bytes": 100
}
},
"registry": {
"HKEY_CURRENT_USER/Software/Game1": {
"failed": true
}
}
},
"Game 2": {
"decision": "Ignored",
"files": {
"/games/game2/save.json": {
"bytes": 50
}
},
"registry": {}
}
}
}
Ludusavi stores its configuration in ~/.config/ludusavi (Windows: C:/Users/<your-name>/.config/ludusavi).
If you're using the GUI, you don't need to worry about this at all,
since the GUI will automatically update the config file as needed.
However, if you're using the CLI exclusively, you'll need to edit config.yaml.
Here are the available settings (all are required unless otherwise noted):
manifest (map):
url (string): Where to download the primary manifest.etag (string or null): An identifier for the current version of the manifest.
This is generated automatically when the manifest is updated.roots (list):
path (string): Where the root is located on your system.store (string): Game store associated with the root.
Valid options: steam, otherbackup (map):
path (string): Full path to a directory in which to save backups.
This can be overridden in the CLI with --path.ignoredGames (optional, array of strings): Names of games to skip when backing up.
This can be overridden in the CLI by passing a list of games.merge (optional, boolean): Whether to merge save data into the target
directory rather than deleting the directory first. Default: false.restore (map):
path (string): Full path to a directory from which to restore data.
This can be overridden in the CLI with --path.ignoredGames (optional, list of strings): Names of games to skip when restoring.
This can be overridden in the CLI by passing a list of games.redirects (optional, list):source (string): The original location when the backup was performed.target (string): The new location.customGames (optional, list):
name (string): Name of the game.files (optional, list of strings): Any files or directories you want
to back up.registry (optional, list of strings): Any registry keys you want to back up.Example:
yaml
manifest:
url: "https://raw.githubusercontent.com/mtkennerly/ludusavi-manifest/master/data/manifest.yaml"
etag: null
roots:
- path: "D:/Steam"
store: steam
backup:
path: ~/ludusavi-backup
restore:
path: ~/ludusavi-backup
Ludusavi also stores manifest.yaml (info on what to back up) here.
You should not modify that file, because Ludusavi will overwrite your changes
whenever it downloads a new copy.
There are other excellent backup tools available, but not a singular cross-platform and cross-store solution:
Please refer to CONTRIBUTING.md.