dir_picker
A Flutter plugin for picking a directory across all platforms using native system dialogs. DirPicker.pick() returns a PickedLocation? (null if the user cancelled). You can then list what's inside with DirPicker.listEntries() or DirPicker.streamEntries(), and keep access to the folder after the app restarts with DirPicker.persist().
Features
- 📁 All Platforms – Android, iOS, macOS, Windows, Linux, and Web
- ⚡ Native Performance – Powered by FFI (iOS/macOS/Windows) and JNI (Android) for near-zero overhead
- 🎨 Customizable Dialogs – Platform-specific options for title, button labels, and more, and an initial folder to open in
- 📜 Directory Listing – list a picked folder at once, or stream large trees in batches and stop early
- 🔗 Persistent Access – keep using a picked folder after the app restarts: persisted URI permissions on Android, bookmarks on iOS and macOS, directory handles in IndexedDB on web
- 🐧 Linux Portals – XDG Desktop Portal with zenity/kdialog fallback
If you want to say thank you, star us on GitHub or like us on pub.dev.
Installation
First, follow the package installation instructions and add
dir_picker to your app.
Quick Start
Platform Setup
Android Configuration
Supported: API 24+ (Android 7.0+)
No configuration needed. The plugin uses the Storage Access Framework (Intent.ACTION_OPEN_DOCUMENT_TREE), which grants URI access through the system picker UI — no manifest permissions required.
iOS Configuration
Supported: iOS 13.0+
No configuration needed. The plugin uses UIDocumentPickerViewController, which is available without extra entitlements.
The plugin ships a privacy manifest (PrivacyInfo.xcprivacy) that declares its file timestamp access (reasons 3B52.1 and C617.1), so App Store Connect sees it without changes to your app's own manifest. The same applies on macOS.
macOS Configuration
Supported: macOS 10.15+
Add the following entitlement to macos/Runner/Release.entitlements and macos/Runner/DebugProfile.entitlements:
<key>com.apple.security.files.user-selected.read-write</key>
<true/>
Windows Configuration
Supported: Windows 10+
No configuration needed. The plugin uses the native IFileOpenDialog COM API.
Linux Configuration
The plugin tries the following dialog backends in order:
- XDG Desktop Portal – Works on all modern desktop environments via D-Bus (
org.freedesktop.portal.FileChooser) - zenity – GNOME fallback
- kdialog – KDE fallback
If none are available, pick() throws an UnsupportedError. To install a fallback manually:
# GNOME
sudo apt install zenity
# KDE
sudo apt install kdialog
Web Configuration
No configuration needed. The plugin uses the File System Access API.
Browser support: pick() needs Chrome 86+ or Edge 86+; it throws UnsupportedError in Firefox and Safari. listEntries() works in any browser for a WebPickedLocation you create from a FileSystemDirectoryHandle, for example one from the origin private file system (navigator.storage.getDirectory()).
Works with both the JavaScript (flutter build web) and WebAssembly (flutter build web --wasm) compilers.
Note: On web,
pick()returns aWebPickedLocationwrapping aFileSystemDirectoryHandle. Use.handleto access directory contents via the File System Access API.PickedLocation.uriis alwaysnullon web — browsers do not expose full filesystem paths. Requirespackage:webin your app's dependencies to work with the handle directly.
Basic Usage
import 'package:dir_picker/dir_picker.dart';
final PickedLocation? location = await DirPicker.pick();
if (location == null) {
print('Cancelled');
} else if (location is WebPickedLocation) {
// Web: use handle to access directory contents via File System Access API
// Requires package:web in your app's dependencies
final handle = location.handle; // FileSystemDirectoryHandle
print('Selected directory: ${location.name}');
} else {
// Native (Android, iOS, macOS, Windows, Linux)
print('Selected: ${location.uri}');
}
List directory entries
final location = await DirPicker.pick();
if (location == null) return;
final entries = await DirPicker.listEntries(location, recursive: true);
for (final entry in entries) {
print('${entry.relativePath} (dir: ${entry.isDirectory})');
}
For large trees, streamEntries emits the same entries while the folder is still being read, so the app can show progress or stop early. Cancelling the subscription stops the walk:
await for (final entry in DirPicker.streamEntries(location, recursive: true)) {
if (entry.name == 'pubspec.yaml') break; // stops reading the folder
}
Open the picker where the user was last time
final next = await DirPicker.pick(initialDirectory: previousLocation);
initialDirectory is a hint: where a platform can't use it, the picker opens in its default place.
| Platform | Supported initialDirectory |
|---|---|
| Android | API 26+. A content:// location from an earlier pick, or an entry's uri (EXTRA_INITIAL_URI). |
| iOS | iOS 13+. A file:// location (UIDocumentPickerViewController.directoryURL). |
| macOS | A file:// location (NSOpenPanel.directoryURL). |
| Windows | A file:// location (IFileDialog::SetFolder). |
| Linux | A file:// location: XDG portal current_folder, zenity --filename, kdialog's start folder. |
| Web | A WebPickedLocation (startIn). It takes precedence over WebOptions.startIn. |
Android: get back a pick lost to a destroyed Activity
Android can destroy the app's Activity, or kill its process, while the system picker is open (low memory, "Don't keep activities"). The app restarts when the user picks, and the pick() call that opened the picker never completes. Call retrieveLostPick at startup to get that folder:
final lost = await DirPicker.retrieveLostPick(); // null on other platforms
if (lost != null) {
// Handle it like the result of pick().
}
Each lost pick is returned once. Call DirPicker.persist on it if you need to keep access.
Keep access to a folder after the app restarts
final prefs = SharedPreferencesAsync();
// After a pick: keep access and save the token.
final token = await DirPicker.persist(location);
await prefs.setString('workspace', token);
// On a later launch: get the folder back without asking the user.
final saved = await prefs.getString('workspace');
final restored = saved == null ? null : await DirPicker.restore(saved);
if (restored == null) {
// Deleted, revoked or released: ask the user to pick again.
}
// When the app no longer needs it.
await DirPicker.release(token);
await prefs.remove('workspace');
| Platform | Token | What persist keeps |
|---|---|---|
| Android | The content:// URI |
A persistable URI permission. Android keeps at most 128 per app (512 from Android 11) and drops the oldest, so release folders you no longer need (see below). |
| iOS | Bookmark data (base64) | A bookmark. restore opens access again until release or the app exits. |
| macOS | Security-scoped bookmark data (base64) | A security-scoped bookmark. Needs the same com.apple.security.files.user-selected.read-write entitlement as pick. |
| Windows, Linux | The file:// URI |
Nothing: the path stays usable. restore returns null once the folder is gone. |
| Web | A random key | The FileSystemDirectoryHandle, in the plugin's IndexedDB database dir_picker. Persisting the same folder again returns the same token. The browser may still ask the user before the page can read it again, see below. |
A bookmark follows the folder when it's moved or renamed, but the token goes stale. Call persist on the restored location and save the new token, as the example app does.
On Android the system keeps the permissions, so one whose token the app never saved (say the app was killed right after persist) still counts toward the limit. persistedTokens lists them, so the app can release the ones it doesn't know:
final saved = await prefs.getString('workspace');
for (final token in await DirPicker.persistedTokens()) {
if (token != saved) await DirPicker.release(token);
}
It lists every folder permission the app holds, including ones taken by other code in the app, so only release what you know is yours. On web it lists the handles persist stored, which only dir_picker writes. Other platforms keep nothing for the app (a bookmark is just the token you saved), so they return an empty list.
On web, the browser decides when to ask again
restore gives back the folder's handle, but reading it needs the user's permission, and the browser may want to ask again. A page can't show that prompt by itself on load: it only appears in response to a click. So restore doesn't check the permission. It returns a WebPickedLocation as long as the token is stored, and the app checks access before reading:
| Situation (Chrome) | hasAccess() |
Reading the folder |
|---|---|---|
Right after pick |
true |
Works |
| Page reloaded while a tab of the site is open | true |
Works |
| All tabs of the site were closed, then the site opened again | false |
Throws LIST_ERROR until requestAccess() from a click |
| The user chose Allow on every visit when asked | true, even after closing tabs or restarting the browser |
Works |
requestAccess() shows Chrome's prompt, which offers Allow this time, Allow on every visit and Don't allow. It returns true when access is allowed. Call it from a button, not on startup: without a click it throws a DirPickerException with PLATFORM_ERROR.
final restored = saved == null ? null : await DirPicker.restore(saved);
if (restored is WebPickedLocation && !await restored.hasAccess()) {
// Show a button; its onPressed runs:
// if (await restored.requestAccess()) listFolder(restored);
} else if (restored != null) {
listFolder(restored);
}
Things to know on web:
- Only Chromium browsers (Chrome, Edge) can pick a folder, so only they can persist one. Firefox and Safari have no
showDirectoryPicker(), so their only directory handles come from the origin private file system: the site's own storage, always readable and writable, with no permission to ask for. That's whyhasAccess()andrequestAccess()returntruethere.falsewould leave an "Allow access" button that can never succeed, and throwing would make every app check the browser first. - A deleted or moved folder still restores, and
hasAccess()can still betrue, since it's about permission only. The browser can't tell until the page reads it, solistEntriesthrowsLIST_ERRORthen. Ask the user to pick again, andreleasethe old token. - Tokens belong to the site's storage. Clearing site data, a private window, or another origin (such as a different port on
localhost) starts with no stored handles, andrestorereturnsnull. - Write access is separate. Pass
mode: WebPermissionMode.readwritetohasAccessandrequestAccessif the app writes to the folder.
PickOptions.android(shouldPersist: true) is deprecated and will be removed in 1.0.0. It takes the same permission during pick, but gives no token; call persist on the result instead.
Platform Options
Pass a PickOptions to DirPicker.pick() to customize the dialog for the current platform:
final location = await DirPicker.pick(
options: PickOptions.macos(acceptLabel: 'Choose', message: 'Select a project folder'),
);
final location = await DirPicker.pick(
options: PickOptions.linux(title: 'Select Folder', acceptLabel: 'Choose'),
);
final location = await DirPicker.pick(
options: PickOptions.windows(title: 'Select Folder', acceptLabel: 'Choose'),
);
final location = await DirPicker.pick(
options: PickOptions.web(
mode: WebPermissionMode.readwrite,
id: 'exports',
startIn: WebStartIn.documents,
),
);
Options for other platforms are silently ignored — only the one matching the current platform is applied.
AndroidOptions (deprecated)
PickOptions.android() and AndroidOptions are deprecated and will be removed in 1.0.0. Their only option, shouldPersist, takes the same permission as DirPicker.persist, which also returns the token to restore it:
// Before
final location = await DirPicker.pick(
options: PickOptions.android(shouldPersist: true),
);
// After
final location = await DirPicker.pick();
if (location != null) {
final token = await DirPicker.persist(location); // save it for restore()
}
MacosOptions
| Parameter | Type | Default | Description |
|---|---|---|---|
acceptLabel |
String |
'Select' |
Label for the confirmation button (NSOpenPanel.prompt). |
message |
String |
'Choose a directory' |
Descriptive text shown inside the panel (NSOpenPanel.message). |
LinuxOptions
| Parameter | Type | Default | Description |
|---|---|---|---|
title |
String |
'Select Directory' |
Window title of the dialog. |
acceptLabel |
String |
'Select' |
Label for the confirmation button (XDG Portal only). |
WindowsOptions
| Parameter | Type | Default | Description |
|---|---|---|---|
title |
String |
'Select Directory' |
Window title of the dialog (IFileDialog::SetTitle). |
acceptLabel |
String |
'Select' |
Label for the confirmation button (IFileDialog::SetOkButtonLabel). |
WebOptions
Passed to window.showDirectoryPicker().
| Parameter | Type | Default | Description |
|---|---|---|---|
mode |
WebPermissionMode |
WebPermissionMode.read |
Access to request. readwrite lets the handle create, change and delete files without asking again. |
id |
String? |
null |
Remembers the last folder picked for this purpose. At most 32 letters, digits, _ or -. |
startIn |
WebStartIn? |
null |
Well-known folder to open in (desktop, documents, downloads, music, pictures, videos) when there's no remembered folder for id. |
Core Concepts
Return value
| Result | Meaning |
|---|---|
IOPickedLocation |
Native platforms — use .uri to get the selected directory URI. |
WebPickedLocation |
Web — use .handle (FileSystemDirectoryHandle) to access directory contents. .uri is null. hasAccess()/requestAccess() check and ask for permission. |
null |
The user cancelled. |
Only one picker can be open at a time. Calling pick() again before the previous call completes throws a DirPickerException with code ALREADY_ACTIVE.
Errors
Failures from the platform throw a DirPickerException. Check its code against the constants on the class; message is for logs and its wording may change:
try {
final location = await DirPicker.pick();
} on DirPickerException catch (e) {
if (e.code == DirPickerException.alreadyActive) return;
print('Picker failed: $e'); // DirPickerException(PICKER_ERROR): …
}
| Code | Constant | When |
|---|---|---|
ALREADY_ACTIVE |
alreadyActive |
pick() while another pick is open. |
PICKER_ERROR |
pickerError |
The picker couldn't be shown or failed: Android launch, zenity/kdialog exiting with an error, a web error other than cancelling. |
PLATFORM_ERROR |
platformError |
A platform call failed: a Windows COM call (with its HRESULT), no view controller on iOS, WebPickedLocation.requestAccess() without a click on web. |
NO_ACTIVITY |
noActivity |
Android: no Activity attached to show the picker from. |
NO_CONTEXT |
noContext |
Android: no application context yet. |
INVALID_URI |
invalidUri |
The location's URI can't be opened as a directory. |
LIST_ERROR |
listError |
listEntries/streamEntries couldn't read the picked directory itself (deleted, not a directory, access lost). |
PERSIST_ERROR |
persistError |
persist couldn't keep access. |
RESTORE_ERROR, RELEASE_ERROR, PERSISTED_TOKENS_ERROR |
restoreError, releaseError, persistedTokensError |
Reading or changing the persisted permissions (Android) or the stored handles in IndexedDB (web) failed. |
Calling the API wrongly, such as passing a web location on Android or a native one on web, throws ArgumentError or UnsupportedError instead.
Native Mechanisms
| Platform | Mechanism |
|---|---|
| Android | SAF (Intent.ACTION_OPEN_DOCUMENT_TREE) via JNI |
| iOS | UIDocumentPickerViewController via FFI |
| macOS | NSOpenPanel via FFI |
| Windows | IFileOpenDialog (COM) via pure Dart FFI |
| Linux | XDG Desktop Portal → zenity → kdialog |
| Web | window.showDirectoryPicker() (JS interop) |
Common Use Cases
Simple directory pick (native)
final location = await DirPicker.pick();
if (location != null) {
print('Selected: ${location.uri}');
}
Simple directory pick (web)
import 'package:dir_picker/dir_picker.dart';
import 'package:web/web.dart' as web; // required to use FileSystemDirectoryHandle
final location = await DirPicker.pick();
if (location is WebPickedLocation) {
final web.FileSystemDirectoryHandle handle = location.handle;
// list files, read contents, etc.
}
Custom dialog labels
final location = await DirPicker.pick(
options: PickOptions.macos(
acceptLabel: 'Use This Folder',
message: 'Select the folder to import from',
),
);
// or on Linux/Windows:
final location = await DirPicker.pick(
options: PickOptions.linux(
title: 'Import Folder',
acceptLabel: 'Use This Folder',
),
);
Keep access after a restart
final location = await DirPicker.pick();
if (location != null) {
final token = await DirPicker.persist(location);
// Save the token; DirPicker.restore(token) gives the folder back later.
}
See Keep access to a folder after the app restarts.
API Reference
DirPicker.pick
static Future<PickedLocation?> pick({PickOptions? options, PickedLocation? initialDirectory})
Returns a PickedLocation (either IOPickedLocation or WebPickedLocation), or null if the user cancelled.
initialDirectory opens the picker in that folder where the platform supports it (see Open the picker where the user was last time).
options is a PickOptions sealed class — pass the platform-specific subclass using its factory constructor (e.g. PickOptions.android(...), PickOptions.macos(...)). Options for other platforms are ignored.
DirPicker.listEntries
static Future<List<FileSystemEntry>> listEntries(
PickedLocation location, {
bool recursive = false,
})
Lists files and directories inside a previously picked location.
Behavior:
- Returns a flat list of descendants under the picked root.
- Excludes the picked root itself.
- Lists only immediate children when
recursiveisfalse. - Lists all nested descendants when
recursiveistrue. - Does not guarantee output ordering.
- Completes only once every entry has been read. For large trees, use
streamEntries.
DirPicker.streamEntries
static Stream<FileSystemEntry> streamEntries(
PickedLocation location, {
bool recursive = false,
})
Emits the same entries as listEntries while the directory is being read: in batches of 200 on Android, iOS and macOS, one directory at a time on web, and one by one on Windows and Linux. Cancelling the subscription stops the walk. A failure to read location itself is emitted as an error.
DirPicker.persist, DirPicker.restore, DirPicker.release, DirPicker.persistedTokens
static Future<String> persist(PickedLocation location)
static Future<PickedLocation?> restore(String token)
static Future<void> release(String token)
static Future<List<String>> persistedTokens()
persist keeps access to a picked or restored location and returns a token to save. restore returns the location with access restored, or null when the token no longer gives access. release gives up that access. persistedTokens returns the tokens of the folder permissions Android keeps for the app, or of the handles stored on web, and an empty list on other platforms. On web, a restored location may need WebPickedLocation.requestAccess() from a click before it can be read. See Keep access to a folder after the app restarts.
DirPicker.retrieveLostPick
static Future<PickedLocation?> retrieveLostPick()
Returns the folder from a pick() whose result came back after Android destroyed the app's Activity, once, or null. Always null on other platforms. See Android: get back a pick lost to a destroyed Activity.
DirPickerException
class DirPickerException implements Exception {
final String code;
final String? message;
}
Thrown for platform failures. See Errors for the codes.
PickedLocation
Base type returned by DirPicker.pick().
| Type | Platform | Notes |
|---|---|---|
IOPickedLocation |
Android, iOS, macOS, Windows, Linux | Provides a non-null uri. |
WebPickedLocation |
Web | Provides a FileSystemDirectoryHandle; uri is always null. hasAccess() and requestAccess() check and ask for permission to it, see On web. |
FileSystemEntry
Model returned by DirPicker.listEntries() and DirPicker.streamEntries().
| Field | Type | Description |
|---|---|---|
name |
String |
Basename of the entry. |
relativePath |
String |
Path relative to the picked root, always using / separators. |
isDirectory |
bool |
Whether the entry is a directory. |
uri |
Uri? |
Native URI when available; always null on web. |
size |
int? |
File size in bytes; null for directories or when unavailable. |
lastModified |
DateTime? |
Last modified timestamp when available. |
PickOptions
Platform-specific options passed to DirPicker.pick().
| Factory | Platform | Purpose |
|---|---|---|
PickOptions.android() |
Android | Deprecated, removed in 1.0.0. Use DirPicker.persist instead. |
PickOptions.macos() |
macOS | Customizes the open panel accept label and message. |
PickOptions.linux() |
Linux | Customizes dialog title and accept label. |
PickOptions.windows() |
Windows | Customizes dialog title and accept label. |
PickOptions.web() |
Web | Sets the access mode, remembered-folder id and start folder. |
Platform Support
| Android | iOS | macOS | Windows | Linux | Web |
|---|---|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
Minimum versions:
- Flutter ≥ 3.44.0
- Dart SDK ≥ 3.12.0
- Kotlin Gradle Plugin 2.0.0+ (enforced by Flutter 3.44)
- Swift 5.9
- Android API 24+
- iOS 13.0+
- macOS 10.15+
- Windows 10+
- Web: Chrome/Edge 86+ for
pick();listEntries()works in any browser with aFileSystemDirectoryHandle
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
MIT License — see LICENSE file for details.