Skip to main content

path_manager 1.0.0 copy "path_manager: ^1.0.0" to clipboard
path_manager: ^1.0.0 copied to clipboard

Plugin for getting commonly used locations on host file system via FFI

Path Manager #

Pub Version License: MIT

A federated Flutter plugin providing unified access to commonly used host filesystem directories across Android, iOS, macOS, Linux, and Windows.

This plugin leverages direct native interop without MethodChannels:

  • Android: Java Native Interface (JNI via package:jni)
  • iOS & macOS: Objective-C FFI via package:objective_c
  • Linux: XDG Base Directory specification via package:xdg_directories
  • Windows: Win32 Shell Known Folders via package:win32

Supported Platforms #

Android iOS macOS Linux Windows
Support API 21+ 13.0+ 10.15+ Any Windows 10+

Application-Scoped Directories #

Application support and cache directories are namespaced per application, matching platform conventions:

Platform Support directory Cache directory
Android Internal app files directory Internal app cache directory
iOS App container Library/Application Support App container Library/Caches
macOS ~/Library/Application Support/<bundle-id> (or the sandbox container equivalent) ~/Library/Caches/<bundle-id> (or the sandbox container equivalent)
Linux $XDG_DATA_HOME/<app-id> $XDG_CACHE_HOME/<app-id>
Windows %APPDATA%\<company>\<product> %LOCALAPPDATA%\<company>\<product>

On Linux, <app-id> comes from the running GApplication when available, falling back to the executable name. On Windows, <company> is omitted when the executable has no company metadata and <product> falls back to the executable name. Documents, downloads, and desktop media directories remain global user directories.


Platform & Method Support #

Method Android iOS macOS Linux Windows Description
getTemporaryDirectory() ✅ ✅ ✅ ✅ ✅ Temporary directory for cache files (subject to OS cleanup).
getApplicationSupportDirectory() ✅ ✅ ✅ ✅ ✅ Application-created directory for app state, databases, etc.
getApplicationDocumentsDirectory() ✅ ✅ ✅ ✅ ✅ User-accessible directory for persistent documents/profiles.
getApplicationCacheDirectory() ✅ ✅ ✅ ✅ ✅ Cache directory (persists longer than temporary files).
getApplicationNoBackupDirectory() ✅ ✅ ✅ ✅ ✅ Resolves a default directory that is excluded from backups.
getExternalStorageDirectory(dir) ✅ ❌ ❌ ❌ ❌ External storage directory for a given StorageDirectory.
getExternalStorageDirectories(dirs) ✅ ❌ ❌ ❌ ❌ List of external storage directories for target dirs.
getExternalCacheDirectories() ✅ ❌ ❌ ❌ ❌ List of external cache directories (Context.getExternalCacheDirs).
getDownloadsDirectory() ✅ ❌ ✅ ✅ ✅ User/app downloads directory.
getTemporaryDirectorySync() ✅ ✅ ✅ ✅ ✅ Synchronous temporary directory.
getApplicationSupportDirectorySync() ✅ ✅ ✅ ✅ ✅ Synchronous application support directory.
getApplicationDocumentsDirectorySync() ✅ ✅ ✅ ✅ ✅ Synchronous documents directory.
getApplicationCacheDirectorySync() ✅ ✅ ✅ ✅ ✅ Synchronous cache directory.
getDownloadsDirectorySync() ✅ ❌ ✅ ✅ ✅ Synchronous downloads directory.
getDesktopDirectory() / getDesktopDirectorySync() ❌ ❌ ✅ ✅ ✅ Global user desktop directory.
getPicturesDirectory() / getPicturesDirectorySync() ❌ ❌ ✅ ✅ ✅ Global user pictures directory.
getMusicDirectory() / getMusicDirectorySync() ❌ ❌ ✅ ✅ ✅ Global user music directory.
getVideosDirectory() / getVideosDirectorySync() ❌ ❌ ✅ ✅ ✅ Global user videos directory.
getDiskSpace({path}) / getDiskSpaceSync({path}) ✅ ✅ ✅ ✅ ✅ Free and total volume capacity in bytes for the volume containing path.
getApplicationCacheSize() ✅ ✅ ✅ ✅ ✅ Recursive application cache size in bytes.
clearApplicationCache() ✅ ✅ ✅ ✅ ✅ Deletes and recreates the application cache directory.
getApplication*Subdirectory(subpath) ✅ ✅ ✅ ✅ ✅ Creates a validated, namespaced subdirectory.
formatBytes(bytes) ✅ ✅ ✅ ✅ ✅ Formats a byte count into a human-readable string.
setApplicationPathIsExcludedFromBackup(...) ❌ ✅ ✅ ❌ ❌ Programmatically toggles the backup exclusion flag.

Installation #

Add path_manager to your pubspec.yaml dependencies:

dependencies:
  path_manager: ^1.0.0

Then run:

flutter pub get

Usage #

import 'dart:io';
import 'package:path_manager/path_manager.dart';

// Retrieve the temporary directory
final Directory tempDir = await PathManager.getTemporaryDirectory();
print('Temporary directory: ${tempDir.path}');

// Retrieve the application documents directory
final Directory docsDir = await PathManager.getApplicationDocumentsDirectory();
print('Documents directory: ${docsDir.path}');

// Retrieve the application support directory
final Directory supportDir = await PathManager.getApplicationSupportDirectory();
print('Support directory: ${supportDir.path}');

// Retrieve the application cache directory
final Directory cacheDir = await PathManager.getApplicationCacheDirectory();
print('Cache directory: ${cacheDir.path}');

// Retrieve the downloads directory
final Directory downloadsDir = await PathManager.getDownloadsDirectory();
print('Downloads directory: ${downloadsDir.path}');

// Retrieve the dedicated directory excluded from backups
final Directory noBackupDir = await PathManager.getApplicationNoBackupDirectory();
print('No-backup directory: ${noBackupDir.path}');

Synchronous Access #

Use the synchronous getters in main(), dependency-injection setup, or database initialization:

final Directory supportDir = PathManager.getApplicationSupportDirectorySync();
final Directory cacheDir = PathManager.getApplicationCacheDirectorySync();

Desktop Media Directories #

Windows, macOS, and Linux expose global user directories. Android and iOS throw UnsupportedError.

final Directory pictures = await PathManager.getPicturesDirectory();
final Directory videos = await PathManager.getVideosDirectory();

Disk Space and Cache Utilities #

getDiskSpace() reports the free and total capacity of the volume containing a path, in bytes. path selects the volume; it does not measure the entity at that path. getApplicationCacheSize() measures only the application cache directory, and clearApplicationCache() deletes and recreates that directory.

final DiskSpace space = await PathManager.getDiskSpace();
print('${PathManager.formatBytes(space.freeBytes)} free of '
    '${PathManager.formatBytes(space.totalBytes)}');

final int cacheBytes = await PathManager.getApplicationCacheSize();
print('Cache: ${PathManager.formatBytes(cacheBytes)}');
await PathManager.clearApplicationCache();

Safe Subdirectories #

Subdirectory helpers create validated, namespaced directories. Absolute paths, drive letters, UNC paths, .. segments, NUL characters, and Windows reserved names are rejected.

final Directory database =
    await PathManager.getApplicationSupportSubdirectory('database/drift');

Federated Architecture #

path_manager is built as a federated plugin:

  • path_manager: App-facing facade package.
  • path_manager_platform_interface: Common platform interface and data structures.
  • path_manager_android: Android implementation using JNI.
  • path_manager_foundation: iOS and macOS implementation using Foundation Objective-C FFI.
  • path_manager_linux: Linux implementation using XDG Base Directory specification.
  • path_manager_windows: Windows implementation using Win32 Shell Known Folders via FFI.