> ## Documentation Index
> Fetch the complete documentation index at: https://filekit.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# App directories

> Find the app files, cache, and databases directories, plus Downloads and other user folders

[See the platform support matrix](https://filekit.mintlify.site/platform-support.md#filekit-core)

`FileKit.filesDir`, `FileKit.cacheDir`, and `FileKit.databasesDir` return the app's private directories as `PlatformFile`s, mapped to each platform's conventions. They are declared in `nonWebMain`, so call them from any source set without JS or Wasm.

## Usage

```kotlin nonWebMain theme={null}
val config = FileKit.filesDir / "config.json"
config.writeString("""{"version": 1}""")

val thumbnail = FileKit.cacheDir / "thumb.jpg"
val database = FileKit.databasesDir / "app.db"
```

On JVM, Linux native, and Windows native, call `FileKit.init(appId)` before reading any of these directories. `FileKit.init(appId, filesDir, cacheDir)` overrides the locations, and `FileKit.init(filesDir, cacheDir)` sets both without an app ID. See [Core setup](https://filekit.mintlify.site/core/setup.md).

## Directory locations

| Platform | `filesDir` | `cacheDir` | `databasesDir` |
| - | - | - | - |
| Android | `Context.filesDir` | `Context.cacheDir` | `databases/` in the app data directory |
| iOS, watchOS | `Documents/` (included in backups) | `Library/Caches/` (not backed up, may be purged) | `Documents/databases/` |
| macOS | `~/Library/Application Support/<bundle id>/` | `~/Library/Caches/` (in the container when sandboxed) | `<filesDir>/databases/` |
| JVM on macOS | `~/Library/Application Support/<appId>/` | `~/Library/Caches/<appId>/` | `<filesDir>/databases/` |
| JVM on Linux, Linux native | `$XDG_DATA_HOME/<appId>/`, default `~/.local/share/<appId>/` | `$XDG_CACHE_HOME/<appId>/`, default `~/.cache/<appId>/` | `<filesDir>/databases/` |
| JVM on Windows, Windows native | `%APPDATA%\<appId>\` | `%LOCALAPPDATA%\<appId>\Cache\` | `<filesDir>\databases\` |

`filesDir` and `cacheDir` always exist when you read them: FileKit creates them on desktop targets if needed. Android and Apple platforms also create `databasesDir` for you.

> [!NOTE]
>
> On JVM, Linux native, and Windows native, `databasesDir` is not created automatically. Call `FileKit.databasesDir.createDirectories()` before writing into it.

On macOS native, `cacheDir` is the shared user Caches folder, not a per-app subfolder. Add your own subfolder, such as `FileKit.cacheDir / "com.example.myapp"`, when your app isn't sandboxed.

## Use the temporary directory on Apple platforms

`FileKit.tempDir` returns `NSFileManager.temporaryDirectory`. It is declared for iOS, macOS, and watchOS only, so call it from an Apple source set such as `appleMain` or `iosMain`:

```kotlin iosMain theme={null}
val scratch = FileKit.tempDir / "upload.tmp"
```

The system can delete this directory's contents when your app is not running.

## Get the project directory in tests

`FileKit.projectDir` exists on every non-web target, but it only makes sense during development and tests:

| Platform | Returns |
| - | - |
| Android, JVM, macOS, Linux native, Windows native | `PlatformFile(".")`: the process working directory. Gradle runs JVM and native host tests from the module directory. On an Android device, `.` is not your project. |
| iOS, watchOS | The folder four levels above the app bundle. For a test binary on the simulator, that is the module directory. On a real device, it doesn't point to your project. |

See [Test resources](https://filekit.mintlify.site/cookbook/test-resources.md) to read fixture files with it. Don't use `projectDir` in production code.

## Open user folders on desktop

On JVM, macOS, Linux native, and Windows native, FileKit resolves the user's Downloads, Pictures, Videos, Music, and Documents folders:

```kotlin jvmMain theme={null}
val downloads: PlatformFile = FileKit.downloadsDir
val pictures = FileKit.userDirectory(FileKitUserDirectory.Pictures)

// Returns null instead of throwing when the folder can't be resolved
val music: PlatformFile? = FileKit.userDirectoryOrNull(FileKitUserDirectory.Music)
```

The shortcuts are `downloadsDir`, `picturesDir`, `videosDir`, `musicDir`, and `documentsDir`. They throw a `FileKitException` when the folder can't be resolved. These APIs are not declared on Android, iOS, watchOS, or the web.

| Platform | Resolution |
| - | - |
| macOS native | Foundation search paths (`Videos` is `~/Movies`). |
| JVM on macOS | `$HOME/<name>`, with `Videos` mapped to `Movies`. |
| JVM on Linux, Linux native | `XDG_<NAME>_DIR` environment variables, then `~/.config/user-dirs.dirs`, then `$HOME/<name>`. |
| JVM on Windows, Windows native | Windows known folders (`SHGetKnownFolderPath`), then `%USERPROFILE%\<name>`. |

On JVM, Linux native, and Windows native, a missing folder is created when you read it.

## Download a file on the web

Browsers have no app directories. To save bytes to the user's Downloads folder, use `FileKit.download`. See [Files on the web](https://filekit.mintlify.site/core/web.md#download-files).

## Related

* [Core setup](https://filekit.mintlify.site/core/setup.md) to set the application ID or custom directories.
* [Writing files](https://filekit.mintlify.site/core/write-file.md) into these directories.
* [Bookmark data](https://filekit.mintlify.site/core/bookmark-data.md) to keep access to files outside them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.