Customizing the shared cache locations

By default, the Package Manager uses the following folder structure for its caches:

<global-cache-root>
  ├── npm
  │   └── <registry data (package metadata and tarballs)>
  ├── packages
  │   └── <uncompressed contents of package tarballs>
  └── git-lfs (if enabled)
       └── <downloaded Git LFS files>

To override the default location of the Package Manager’s global cache root, you can use either the cacheRoot property in the user configuration file or set the UPM_CACHE_ROOT environment variable.

Note: For macOS and Linux systems, consider using the user configuration file strategy for macOS and Linux systems, because it can be hard to launch Unity with environment variables on those systems.

You can also set environment variables to override the registry data cache, the uncompressed packages cache, and the Git LFS cache. However, environment values and configuration file properties are not equivalent, so using different methods to configure settings can produce unexpected results.

There are many factors affecting how setting several values with different methods works together:

• If you set different values for the global cache root with both the UPM_CACHE_ROOT environment variable and the cacheRoot property, Package Manager uses the location in the UPM_CACHE_ROOT environment variable.
• If you set an environment variable for the registry data cache (UPM_NPM_CACHE_PATH), the uncompressed packages cache (UPM_CACHE_PATH), or the Git LFS cache (UPM_GIT_LFS_CACHE_PATH), Package Manager uses the location specified by the environment variable, regardless of where the global cache root is.
• When you use a user configuration file, the change is applied to the current user account. Although a global configuration file exists, you cannot apply this change to the global file.
• If you enable the Git LFS cache (UPM_ENABLE_GIT_LFS_CACHE) without explicitly setting its path (UPM_GIT_LFS_CACHE_PATH), Package Manager uses the git-lfs folder under the global cache root as its location.

Using the user configuration file

You can manually edit the user configuration file to override the location of the global cache root. Although a global configuration file exists, you can’t set the global cache location in the global configuration file.

Follow these steps to override the location of the global cache root for the current user:

1. Locate the .upmconfig.toml user configuration file. To find the file location, see Configuration files. If the file doesn’t exist, create an empty text file.

2. Add the cacheRoot key and set its value as an absolute path to a custom location. Important: When setting Windows paths in TOML files, use forward slashes (/) or double backslashes (\\). Don’t use single backslashes (\) because they’re special characters which mark escape sequences and can cause TOML parsing errors.

   Windows example

   cacheRoot = "E:\\Unity\\cache"
   

   macOS and Linux example

   cacheRoot = "/dev/external/shared/Unity/cache"
   

You don’t need to restart the Unity Editor or the Hub after setting the cacheRoot key for the change to take effect.

Using environment variables

You can use environment variables to configure several settings for the Package Manager. However, in order for these settings to apply, you have to launch Unity or the Hub from a terminal or command prompt where those environment variables have been defined and exported every time.

For example, you can run these commands in a macOS or Linux terminal to configure the location of the global cache root and enable the Git LFS cache:

# On macOS/Linux:
export UPM_CACHE_ROOT=/dev/ssd/shared/Unity/cache
export UPM_ENABLE_GIT_LFS_CACHE=true
echo "Launching Unity with the Git LFS cache enabled and using this global cache location: '$UPM_CACHE_ROOT'"
"/Applications/Unity Hub.app/Contents/MacOS/Unity Hub"

This Windows example configures the locations of both the global cache root and the Git LFS cache:

# On Windows:
set UPM_CACHE_ROOT=%ALLUSERSPROFILE%\Unity\cache
set UPM_GIT_LFS_CACHE_PATH=%ALLUSERSPROFILE%\repos\caches\lfs
echo "Launching Unity with this global cache location: '%UPM_CACHE_ROOT%'"
echo "... and this Git LFS cache location: '%UPM_GIT_LFS_CACHE_PATH%'"
"C:\Program Files\Unity Hub\Unity Hub.exe"

The following environment variables are available: