multiplatform-path-provider

Unified API for retrieving system app directories (temp, documents, cache, downloads), synchronous calls, application-id isolation for per-app subdirectories and standard path mappings.

#windows
#utility
#native
#macos
#linux
#desktop
#apple

Suggest an edit

Android JVMJVMKotlin/Native

GitHub stars1

Authorsloshine

Open issues0

LicenseApache License 2.0

Creation date5 months ago

Last activity5 months ago

Latest release0.0.1 (5 months ago)

GitHub repository Wiki page

Multiplatform Path Provider

中文版

A Kotlin Multiplatform library meant to provide a unified API to access platform-specific application directories (like temp, documents, cache, etc.) across multiple targets.

Inspired by Flutter's path_provider.

Supported Platforms

Android
iOS
macOS
tvOS
Linux (X64, Arm64)
Windows (Mingw X64)
JVM (Desktop - Windows, macOS, Linux)

Installation

Add the dependency to your build.gradle.kts:

commonMain.dependencies {
    implementation("io.github.loshine:multiplatform-path-provider:0.0.1")
}

Setup

Desktop & Native (JVM, Linux, Windows)

On desktop and native platforms, you should set the Application ID. This ID is used to create isolated subdirectories for your application in shared system locations (like Application Support or Cache).

import io.github.loshine.multiplatform.pathprovider.setApplicationId

fun main() {
    setApplicationId("com.example.myapp")
    // ...
}

Note: On Android and Apple platforms (iOS, macOS, tvOS), setApplicationId is a no-op because the operating system handles sandboxing automatically.

Usage

All functions are synchronous and can be called directly.

import io.github.loshine.multiplatform.pathprovider.getTemporaryDirectory
import io.github.loshine.multiplatform.pathprovider.getApplicationDocumentsDirectory
import io.github.loshine.multiplatform.pathprovider.getApplicationCacheDirectory

// Call directly anywhere
val tempDir = getTemporaryDirectory()
val docDir = getApplicationDocumentsDirectory()
val cacheDir = getApplicationCacheDirectory()

Supported Paths

Function	Android	Apple (Native)	Linux (Native)	Windows (Native)	JVM
`getTemporaryDirectory()`	`cacheDir`	`NSTemporaryDirectory`	`/tmp`	`%TEMP%`	`java.io.tmpdir`
`getApplicationSupportDirectory()`	`filesDir`	`NSApplicationSupportDirectory`	`~/.local/share/<appId>`	`%APPDATA%\<appId>`	`%APPDATA%` (Win) `App Support` (Mac) `~/.local/share` (Linux)
`getApplicationDocumentsDirectory()`	`dataDir`	`NSDocumentDirectory`	`~/Documents`	`~/Documents`	`~/Documents`
`getApplicationCacheDirectory()`	`cacheDir`	`NSCachesDirectory`	`~/.cache/<appId>`	`%LOCALAPPDATA%\<appId>`	`AppData/Local` (Win) `Library/Caches` (Mac) `~/.cache` (Linux)
`getDownloadsDirectory()`	`ExternalFiles/Download`	`NSDownloadsDirectory`	`~/Downloads`	`~/Downloads`	`~/Downloads`
`getApplicationLibrary()`	Not Supported	`NSLibraryDirectory`	Not Supported	Not Supported	`~/Library` (Mac only)
`getExternalStorageDirectory()`	`getExternalFilesDir(null)`	Not Supported	Not Supported	Not Supported	Not Supported
`getExternalStorageDirectories()`	`getExternalFilesDirs(null)`	Not Supported	Not Supported	Not Supported	Not Supported
`getExternalCacheDirectory()`	`externalCacheDir`	Not Supported	Not Supported	Not Supported	Not Supported
`getExternalCacheDirectories()`	`externalCacheDirs`	Not Supported	Not Supported	Not Supported	Not Supported

Note: Mappings for Linux and Windows may vary based on XDG_* environment variables or system configuration.

License

Copyright 2025 Loshine

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.