Set cache via environment variable

Is there a way to set the cache directory via an environment variable? When working at the command line it is quite annoying to manually type --cache-dir on every command.

Is TMPDIR == --cache-dir? mentions XDG_CACHE_HOME, I set this variable but restic seems to be using the existing variable instead.

Uhm, the variable you’ve mentioned (XDG_CACHE_HOME) is correct, if it is set and the flag --cache-dir is not present, restic uses the directory $XDG_CACHE_HOME/restic for its cache.

The priority for selecting the cache directory is as follows:

  • Command-line flag --cache-dir
  • Environment variable $XDG_CACHE_HOME
  • Default (~/.cache/restic)

Can you paste your complete command line?

Sure. Earlier in the script I set:

SET B2_ACCOUNT_ID=<removed>
SET B2_ACCOUNT_KEY=<removed>
SET RESTIC_PASSWORD_FILE=%@full[Utils:restic.txt]
SET RESTIC_REPOSITORY=b2:%[projectname]:restic-%[computername]
SET XDG_CACHE_HOME=D:\restic-cache

Then later I call restic multiple times. Here’s one:
restic --tag IIS backup C:\inetpub D:\HTTP "C:\Windows\System32\inetsrv\config"

Since the B2_ and RESTIC_ variables are required for restic to run, I am confident that all the variables have been set correctly. I also tried pasting each command at the command line, running restic, and then verifying the environment variables are still set correctly.

I deleted the current cache (in case restic checks in the default location for a cache first), then ran restic and this is the output:

repository fee88442 opened successfully, password is correct
created new cache in C:\Users\daveadmin\AppData\Local\restic
Files: 0 new, 1 changed, 287 unmodified
Dirs: 0 new, 1 changed, 4 unmodified
Added to the repo: 486.756 KiB
processed 288 files, 26.162 MiB in 1:13
snapshot b1a2475c saved

D:\restic-cache does exist, permissions are good, but it remains empty.

XDG_CACHE_HOME is only used on platforms that aren’t Darwin (OS X) or Windows.

On Windows, it uses %LOCALAPPDATA%\restic as the default.

Another option is to put common arguments in a variable, for example:

set RESTIC_CMD=restic --cache-dir=...
%RESTIC_CMD% backup ...

I don’t know how to do this in Windows, but if you’re working with a script then in bash you could to something like this:

restic "$@" --cache-dir=/path/to/your/cache/dir

Then, every time you call the script, you can use any command and it will use the cache directory specified in your script.

True, it just adds complexity when all the other “include it on every single command” things can be defined in the environment.

Would it be possible to adds a environment variable for this one? I’d suggest it should be checked between the command line and XDG variables.

Yes, it’d be possible. Can you please report this as a feature request on GitHub, so we can track it? Thanks!

I’ve had difficulties with cache size, and it’s taken me some time (yes, newbie) to work out that the command-line flag --cache-dir only affects the current command - it doesn’t effect subsequent commands in the same session. Setting environment variable XDG_CACHE_HOME seems to effect subsequent commands in the same session (on linux at least), and seems more relevant for many situations. I recommend mentioning this variable in the Restic documentation, especially at Based on my limited experience and initial difficulties, I’d also recommend a specific sub-section on managing the cache under the “Backing Up” section of the Restic documentation This is likely to help new users initiating large backups.

I suspect there’s a better place to make these recommendations - please feel free to point me in the right direction.

FWIW, this variable is mentioned in the caching section of the manual.

Huh, that’s interesting! I think we can improve the documentation as you suggested. But I’m curious: What made you think the flag would persist for further invocations of restic? :slight_smile:


To be honest, I lack professional experience as a programmer. Currently I use linux/open source to advance my (and my community’s) digital rights and capacity, learning on ad hoc basis as I deal with personal computing needs. It’s only during my introduction to restic that I’ve come to a basic understanding of environment variables. I might not ever gain an overall understanding of how different frameworks for programming variables fit together!

I received restic forum advice from @dionorgua - see Fatal: Unable to Save Snapshot - suggesting I move the cache location to a larger filesystem by using this flag.

I think it’s too small. Consider using --cache-dir option with restic to move cache to some other place…

When I looked up this restic documentation

There was nothing explicit about the flag only affecting current command, or about how to change the default cache location for a whole terminal session, or permanently. Yes, the caching section of the manual says:

The cache is automatically created, usually in an OS-specific cache folder:

  • Linux/other: ~/.cache/restic (or $XDG_CACHE_HOME/restic )

but I lacked the background knowledge to understand this meant $XDG_CACHE_HOME was an environment variable that could be set for a whole session/script.

Restic seems to be a fantastic tool, and well-supported by you and your partners. I’ve made my suggestions regarding the documentation because there seems to be a number of restic users with a command line skill-base similar to my own, who would benefit from the proposed changes. Thanks for responding :slightly_smiling_face:

1 Like

PS. As someone running restic on a NAS, I may be part of a subgroup of restic users who will run into issues with the default cache location because they are operating on embedded linux systems with small amounts of memory. In my case:

1 Like