Flutter File Picker for Native File Selection

A single Flutter API across operating systems

flutter_file_picker addresses a common Flutter application need: letting users browse for files or directories through the file explorer supplied by the host platform. The README describes support for Android, iOS, Linux, macOS, Windows, and Web. It also covers selecting one file or multiple files, filtering by extension, choosing directories, and opening save-file dialogs. This makes it relevant to applications that import documents, accept attachments, select output directories, or ask users where to save generated content.

The project is not implemented as one plugin binary with platform conditionals throughout its public API. It is a federated plugin organized as a Melos workspace. The main `file_picker` package provides the shared facade, while separate packages implement the native integration for each platform. The README says that applications should normally depend only on `file_picker`; Flutter's plugin system pulls in the appropriate implementation automatically. A direct dependency on a platform package is reserved for APIs that are not exposed by the shared facade.

The federated package structure and platform implementations

The repository layout exposes the central pieces of the design. `file_picker` is the application-facing package. `file_picker_platform_interface` contains the shared contracts and data classes, including `PlatformFile`, `FileType`, and platform option classes. The platform packages are `file_picker_darwin` for iOS and macOS, `android_file_picker` for Android, `file_picker_linux` for Linux, `windows_file_picker` for Windows, and `file_picker_web` for Web.

Each implementation uses a different native integration. The README identifies `file_picker_darwin` as the iOS and macOS implementation, Android support as including the Storage Access Framework, Linux support as using GTK3 and XDG Desktop Portals, and Windows support as using Win32 COM APIs. The Web package includes Wasm compilation support. These differences matter when an application depends on a particular operating-system capability. The facade can present a consistent call shape, but the repository documentation does not claim that every platform has identical behavior for every option.

A returned selection is represented through the shared `PlatformFile` contract. The README's migration notes say that upgrading from pre-v12 changes the behavior of `FilePicker.pickFiles()` to return `List<PlatformFile>`, adds platform options, and introduces streaming. These are interface changes, not merely documentation changes, so applications should account for them during upgrades.

Installing `file_picker` and making a first selection

The README gives a short first use for an application that needs one file. Add the package under `dependencies` in the Flutter project's `pubspec.yaml`. The repository README currently shows version constraint `^13.0.0`, even though its recent releases are v12 releases. That difference should be checked against the package source and changelog before copying the constraint into an application.

Add this dependency declaration to `pubspec.yaml`:

dependencies:
  file_picker: ^13.0.0

Import the public API and call `FilePicker.pickFile()`. The result is nullable, so the example checks for `null` before reading the file name and length.

import 'package:file_picker/file_picker.dart';

final file = await FilePicker.pickFile();
if (file != null) {
  print(file.name);
  print(await file.length());
}

According to the README, `file.length()` returns `Future<int?>`, while `file.lengthSync()` is also available. A successful selection should therefore produce a `PlatformFile` with a name. A cancelled or otherwise absent selection is represented by `null`. The repository does not make this quick start a complete permission guide, so applications should consult the platform package README before testing on a real target.

Multiple files, filters, directories, and save dialogs

The package documentation identifies additional selection modes beyond the single-file example. Multiple-file selection is supported, as are extension filters and directory selection. Save-file dialogs are also available. These features are exposed through the main `file_picker` package rather than requiring application code to import every platform package.

The pre-v12 migration notes also mention streaming. That indicates a path for handling selected data without relying only on the older file-oriented flow. The README excerpt does not provide the complete signatures or a worked streaming example, so the full package README and API reference should be used before designing data movement for large files.

Platform option classes are another important part of the public surface. The shared package includes them so callers can pass platform-specific settings through the common architecture. The repository specifically gives `FilePickerDarwin.skipEntitlementsChecks()` on macOS as an example of an API that is not part of the facade and requires using a platform package directly. This is a good illustration of the boundary: most applications should not need the implementation package, but an application with a specific macOS entitlement workflow may need it.

The README does not claim identical support for every selection mode on every platform. It instead points to a platform compatibility chart in the main package documentation. An application combining several features, such as directory selection, streaming, and Web support, should check that chart before settling on the API.

Native platform constraints and failure cases

The principal limitation is that a cross-platform API does not erase platform-specific setup. macOS has entitlement notes in `file_picker_darwin`, and Android has notes in `android_file_picker`. Linux relies on GTK3 and XDG Desktop Portals, while Windows uses Win32 COM APIs. A build can therefore require platform configuration even when the Dart call is unchanged. The README does not document a universal setup procedure for every target.

Web support has a separate implementation and includes Wasm compilation support, but the documentation does not explain the browser requirements, upload handling, or any size restrictions in enough detail to infer them. Similarly, the repository does not document rollback behavior for a failed dialog, nor does it state that selected files are copied into a uniform location. Those details should remain unknown rather than being assumed.

Version compatibility is another concrete constraint. The migration guide calls out the change from `PlatformFile.length` behavior to `Future<int?>` for v13 and removal of legacy v12-deprecated parameters. Applications that use a custom platform package, named parameters, or old result types need to review the migration guide and changelog. A facade package can reduce conditional code, but it cannot remove the need to test each target platform.

Development, maintenance, and licensing

The repository is a workspace with package-level `pubspec.yaml` files and separate `CHANGELOG.md` files. Its contribution instructions use Melos. The README documents these commands for local workspace setup and validation:

dart pub global activate melos
melos bootstrap

The README also identifies analysis and test tasks for every package:

melos run analyze
melos run test

These commands are repository contributor commands, not application setup steps. Each package is released independently, and the README says only the changed packages need a version bump. That arrangement reduces the need to maintain one monolithic package, but it also means an application may depend on several published packages whose versions and changelogs need review during upgrades.

The repository's last push was on 2026-10-15. It is not archived, so the available facts do not indicate an abandoned repository. The recent release list includes `v12.0.0` dated 2026-08-14 and earlier v12 beta releases, while the quick start references `file_picker` version `^13.0.0`. That version mismatch is a specific maintenance item to resolve through the package changelog or pub.dev metadata before selecting a dependency constraint.

All packages in the repository are released under the MIT license according to the README. This identifies the declared license for the code, but an application owner still needs to check the license text and dependency tree when deciding how the package fits into a distribution. No legal interpretation is required to understand the repository's stated licensing choice.

A practical alternative: platform APIs or separate packages

An alternative is to call each target platform's native file selection mechanism directly through Flutter platform channels or platform-specific plugins. The difference is architectural. `flutter_file_picker` hides the platform split behind a shared `FilePicker` API and platform packages registered by Flutter, while a direct platform approach gives the application more control over each operating system's dialog and permission model but requires conditional integration code.

For an application supporting one platform, direct platform APIs may be simpler if its team already owns that platform's file selection setup. For an application targeting the full range named by the repository, the federated package reduces the number of public APIs that application code must manage. The trade-off is that platform-specific capabilities and setup remain relevant, as shown by the separate Darwin, Android, Linux, Windows, and Web packages.

Editorial conclusion

Use flutter_file_picker when a Flutter application needs native file browsing or save dialogs through one shared API, especially when the application targets several operating systems. Do not choose it merely to inspect arbitrary application files without checking platform permissions, implementation differences, or the v13 migration requirements. First verify the exact `file_picker` version in your application, then review the platform package setup for each target, especially Android, macOS, Linux, Windows, and Web.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. vicajilau/flutter_file_picker on GitHub