App directories

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

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

​

Usage

nonWebMain

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.

​

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.

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:

iosMain

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 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:

jvmMain

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.

​

Related

• Core setup to set the application ID or custom directories.
• Writing files into these directories.
• Bookmark data to keep access to files outside them.