> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/shadefs/managing-the-shadefs-cache.md).
# Managing the ShadeFS Cache
## **Overview**
ShadeFS uses a local cache system to enable smooth, efficient access to your cloud-stored media files. Understand how to configure and manage this cache to optimize your workflow performance and manage your local storage.
## **Cache Basics**
By default, ShadeFS allocates 26GB of cache space in the `.shade` folder within your computer's user root directory. This cache serves as a temporary storage location for streamed media segments so your file explorer and NLE’s have instant access to your media.
## **Location Management**
You can change where ShadeFS stores its cache to a folder on your machine, or an external device:
1. Open **Settings > ShadeFS > Cache Management** in the Shade desktop app (on desktop app version 2.3.21 and earlier, open **Settings > ShadeFS > Configuration** instead)
2. Under **Cache Settings**, click the **ShadeFS cache directory** field
3. Select your preferred cache directory
ShadeFS restarts in the background after you change the cache location.
For optimal performance, we recommend using a high-speed external SSD (such as a Samsung T7) as your cache location. This config will be higher performance and also keep your system drive free for other operations.
Because ShadeFS uses sparse files for cache files, your cache drive must be formatted as APFS (macOS), NTFS or ReFS (Windows), or ext4, XFS, or Btrfs (Linux). Drives formatted as exFAT or Mac OS Extended (HFS+) can't be used for the cache.
Changing the cache directory moves your cached file data. ShadeFS keeps its drive database and a small index of what's cached in the `.shade` folder in your home directory, so leave a little free space on your system drive too.
## **Cache Size**
Cache size can be changed with the **Cache size (GB)** setting in **Settings > ShadeFS > Cache Management**, or through **Edit cache size** in the "Mount Drives" panel. The minimum cache size is 1 GB. The default 26GB cache is sufficient for basic operations, but you can increase this up to the available free space on your computer or whatever your cache directory is set to. Consider your typical workflow project size and available storage when adjusting these settings. The cache size is shared between all drives. If you have multiple drives mounted at the same time, they will all share the same cache space.
## **How ShadeFS Frees Up Space Automatically**
Every 5 minutes, ShadeFS checks how much cache it's using. If it's over your cache size, it removes the files you used least recently until the cache is back down to 90% of your limit.
* **Whole files are removed, never parts of files.** Set your cache size larger than the largest file you work with, or that file will keep being removed and downloaded again.
* **The cache can briefly go over your limit.** Because cleanup runs every few minutes, heavy use can push the cache past your cache size until the next pass.
* **Some files are never removed automatically:** pinned files, files you've opened in the last minute or are still reading, files that are uploading, and files with changes that haven't synced yet.
* **Old copies are cleaned up regardless of size.** Cached copies of files that are no longer in any drive, such as deleted files or earlier versions of a file that's been replaced, are removed on the next pass.
## **Cache and Disk Space Alerts**
The desktop app notifies you when space is getting tight. Click the notification to open **Cache Management**.
* **Shade cache is nearly full / Shade cache is full**: your cache is close to or at your cache size. Shade clears older files automatically, but files that are uploading or open can't be cleared until they finish. If this keeps happening, increase your cache size.
* **Disk space is running low / Disk is almost full**: the disk that holds your cache is running out of space. When it's almost full, files that aren't already cached may not open, and writes to the mounted drive pause until space frees up.
## **Freeing Up Cache Space**
The **Cache Management** page shows how much of your cache is in use and lets you clean it up:
* **Usage** shows how much of your cache size is used, plus how much disk space your pinned files take up.
* **Safe to clear** lists cached files you can remove. Click **Remove** next to a file to clear just that file, or **Clear all** (then **Confirm clear all**) to clear them all.
* **Pinned** lists your pinned files. Click **Unpin** next to a file, or **Unpin all**. Unpinning a file also removes its cached copy.
* **In use** lists files that are uploading or have unsynced changes. These can't be cleared.
* **Unlinked** lists files left behind by drives that are no longer on this machine. Click **Clear** to remove them.
* **Danger Zone > Full reset**: **Clear all Caches and Reset** stops ShadeFS and deletes everything in the cache, including pins and unsynced changes. Only use this as a last resort.
## **Offline Access**
For situations where you need guaranteed access to specific files without internet access, you can pin files offline. When you pin a file or folder, ShadeFS downloads a complete copy and keeps it in your cache directory, making it available offline. Pinned files don't count toward your cache size limit, which means that pinning does not consider the amount of storage your machine has. If you try to pin more storage than you have available, then your machine will run out of space and you will experience problems. To pin content:
1. Navigate to the desired file or folder in the Shade application
2. Right-click the item
3. Select "Pin to Cache"
More info here: [Pinning Files Offline](/shadefs/pinning-files-offline.md)
## **Performance Considerations**
Your cache configuration directly impacts system performance. For the best experience:
* Use a high-speed storage device for your cache location, for suggested hardware check out [Choosing an External SSD for Shade Cache](https://academy.shade.inc/shadefs/choosing-an-external-ssd-for-shade-cache)
* Allocate sufficient cache size for your typical working set
* Monitor available space on your cache drive
* Consider pinning frequently-used files for consistent access
Remember that while larger cache sizes can improve performance with frequently accessed files, they also require more storage space on your local system.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://academy.shade.inc/shadefs/managing-the-shadefs-cache.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
