Register

Troubleshooting: Backing Up and Moving Your User Data

Overview

Foundry Virtual Tabletop stores your User Data in a separate directory than the core software in order to keep it separate from the software and protect it during update periods. This directory, known as your User Data Directory, contains the configuration settings for Foundry VTT as well as all the information for your Worlds, Add-On Modules, Game Systems, and any assets you upload directly through Foundry VTT.

This article will guide you through the process of backing up your User Data, what pieces are most important to store, and how to move your User Data folder to a new location. We recommend making regular backups of your User Data, and especially before moving your User Data or updating Foundry Virtual Tabletop.

Note: Since Foundry VTT 11.5 it is recommended to use the built-in backup tool for backing up your data.

Danger of Data Sync Backup Services

Data sync services such as those offered by Dropbox, Google Drive, and Microsoft OneDrive, are not compatible with Foundry VTT. Foundry VTT makes frequent changes to your World's database files while running. A data sync service will inevitably attempt to copy these databases mid-operation, and can result in them being restored to a broken state at a later time, which can lead to database corruption and irreversible data loss. It is important to never use use a data sync service while Foundry VTT is running, you will permanently lose your work!

Backing Up Your User Data

When performing a backup, it is sometimes useful to know which files are most important to you for long term storage. The steps below go through the absolute basic approach of backing up the entire contents of the User Data folder, but if you wish to perform a more selective back up, use the following list as a guide for which folders are the most important to you:

Config
The folder which stores important settings and secured information, including the settings you configure from the main menu. This folder is not accessible for storing assets from within Foundry VTT. It's usually advisable to back this up if you don't want to have to reconfigure your server in the event something goes awry.
Logs
These shouldn't need to be backed up, as the logs folder only stores the running log containing any errors or messages related to running the server.
Data
This folder is the equivalent to the "root" folder of Foundry VTT, and contains all assets you upload, as well as your modules,systems, and worlds. Backing this folder up in entirety is the most certain way to be able to restore your Foundry VTT to exactly the way it previously was.
Data/worlds
This should be your highest priority when backing up. If you back up nothing else, you should backup your worlds, as they store all of the information for your games.
Data/modules
These are the modules you have installed. If you use a lot of modules, you may want to back these up as well as it will make restoring them convenient.
Data/systems
These are the game systems you have installed. Most people don't use a diverse enough number of systems that they can't be conveniently reinstalled, so this folder rarely needs to be backed up completely..
Default User Data Locations

Depending on your operating system, your User Data folder may be located in different locations. The defaults are:

  • Windows 10 - %localappdata%\FoundryVTT\
  • macOS - ~/Library/Application Support/FoundryVTT
  • Linux - ~/.local/share/FoundryVTT

These are the default locations, but you can change the location of your User Data folder either by changing the User Data path from the setup menu, or by editing the options.json file in your Config directory. You can find more information about this process below.

Performing A Backup For Windows
  1. Launch Foundry VTT and right-click its icon in the taskbar. Click on 'Browse User Data.'
  2. Close Foundry VTT by clicking the X in the top right corner. It should no longer show in the task bar.
  3. Copy the 'Data', 'Config', and 'Logs' folders to another location on your PC.
Performing A Backup For macOS
  1. Launch Foundry VTT and navigate to the Configuration screen.
  2. Copy the filepath from 'User Data Path'.
  3. Close out of Foundry VTT by going to 'Foundry Virtual Tabletop' in the top bar and selecting 'Quit.'
  4. Open 'Finder'.
  5. From the top menu bar, select 'Go' and then 'Go to Folder...'. Or, press Shift+Command+G
  6. Paste in the filepath copied from the Configuration Screen and press Return.
  7. Copy the 'Data', 'Config', and 'Logs' folders to another location.
Performing A Backup For Linux

These steps should apply for the most common Linux distributions, if they do not apply for your distribution you may need further assistance which you can receive on our community discord server.

  1. Launch Foundry VTT and navigate to the Configuration screen.
  2. Copy the filepath from 'User Data Path'.
  3. Close Foundry VTT. If you're using a process manager to run Foundry VTT, check that its process is no longer running.
  4. Open a terminal and navigate to your User Data folder by entering cd </path/to/userdata/here>, pasting the copied path from before in place of </path/to/userdata/here>.
  5. Create a compressed archive by entering tar -czvf foundry-backup.tar.gz Data Config then pressing 'Enter.'
  6. After the archive has finished, move it to another location. You can do this in the terminal using the mv command, eg mv -v foundry-backup.tar.gz ~/ which will place it in your Home directory.

Restoring Your User Data

Restoring your data is as simple as closing Foundry VTT and replacing the Data, Config, and Logs directories with those stored in your backup. Always check that your backup contains your data before overwriting or deleting any existing content.

If you are using a Linux Desktop Environment such as GNOME or KDE, you can simply navigate this process using your preferred file browser, which likely supports compressing and decompressing archive files in-place by drag and drop or context menu actions.

After doing this, launch Foundry Virtual Tabletop as normal.

Moving Your User Data

Moving your User Data to a new location requires just a few simple steps. Before you do so, you should first perform a complete backup of your existing data using the steps above.

Moving User Data For Windows
  1. Launch Foundry VTT and right-click its icon in the taskbar. Click on 'Browse User Data.'
  2. Close Foundry VTT. Open a new file browser window and navigate to where you wish to move your data to. Create a new folder.
  3. Copy the 'Data', 'Config', and 'Logs' folders to this new location. Keep this window open. We will refer to this location as the "old location."
  4. Launch Foundry VTT and navigate to the Configuration screen.
  5. Under 'User Data Path', enter the path to your new User Data location. Click on 'Save Configuration.' Foundry VTT will shut down.
  6. Re-Launch Foundry VTT and check if your worlds are present. If they're not, double check the path you set in the Configuration screen.
  7. If your worlds are present, shut down Foundry VTT. Temporarily move the 'Data', 'Config', and 'Logs' folders from the old location to another folder.
  8. Launch Foundry VTT again. If your worlds are present, you have successfully moved your User Data to a new location.

If your worlds do not show up after completing these steps, double check that the assigned User Data Path is correct and that the folders in this location are not empty.

Moving User Data For macOS
  1. Open Foundry VTT. Navigate to the 'Configuration' screen. Copy the filepath from the field next to 'User Data Path.'
  2. Close Foundry VTT. Open Finder, click the 'Go' menu, choose 'Go to folder...', and paste in the path you copied.
  3. Copy the 'Data', 'Config', and 'Logs' folders to this new location. Keep this window open. We will refer to this location as the "old location."
  4. Launch Foundry VTT and navigate to the Configuration screen.
  5. Under 'User Data Path', enter the path to your new User Data location. Click on 'Save Configuration.' Foundry VTT will shut down.
  6. Re-Launch Foundry VTT and check if your worlds are present. If they're not, double check the path you set in the 'Configuration' screen.
  7. If your worlds are present, shut down Foundry VTT. Temporarily move the 'Data', 'Config', and 'Logs' folders from the old location to another folder.
  8. Launch Foundry VTT again. If your worlds are present, you have successfully moved your User Data to a new location.

If your worlds do not show up after completing these steps, double check that the assigned User Data Path is correct and that the folders in this location are not empty.

Moving User Data For Linux
  1. Open Foundry VTT. Navigate to the 'Configuration' screen. Copy the filepath from the field next to 'User Data Path.'
  2. Close Foundry VTT and open a file browser window enter in the path you copied.
  3. Copy the 'Data', 'Config', and 'Logs' folders to this new location. Keep this window open. We will refer to this location as the "old location."
  4. Launch Foundry VTT and navigate to the Configuration screen.
  5. Under 'User Data Path', enter the path to your new User Data location. Click on 'Save Configuration.' Foundry VTT will shut down.
  6. Re-Launch Foundry VTT and check if your worlds are present. If they're not, double check the path you set in the Configuration screen.
  7. If your worlds are present, shut down Foundry VTT. Temporarily move the 'Data', 'Config', and 'Logs' folders from the old location to another folder.
  8. Launch Foundry VTT again. If your worlds are present, you have successfully moved your User Data to a new location.

If your worlds do not show up after completing these steps, double check that the assigned User Data Path is correct and that the folders in this location are not empty.