file_picker v13: Federated Plugins and a Maintenance Handoff

file_picker is one of those packages every Flutter developer has added at some point — the native file explorer, single or multiple picks, extension filtering. What many of its users have not noticed is that under the hood it underwent two structural changes that matter if you depend on it: a move to a federated plugin architecture in v12, and a maintainer handoff in 2026. Both shape how the package behaves and how you should migrate.

Source: file_picker package page, victorcarreras.dev, pub.dev.

What “federated” means here

A federated plugin splits what looks like one package into three layers:

• The app-facing package (file_picker) — the API you import.
• A platform interface (file_picker_platform_interface) — the abstract contract each platform implements.
• Per-platform implementations — file_picker_darwin, file_picker_web, file_picker_linux, android_file_picker, windows_file_picker, and more.

The win is that a platform implementation can be updated — or even swapped — independently of the main package. Web support can ship a fix without waiting on a coordinated release of everything. For you as a consumer, the API surface stays stable while the machinery underneath becomes maintainable per platform. file_picker’s dependency list now reflects exactly this split.

The v12 breaking changes

The federation came with a real API reshape. If you are still on v11, these are the changes that will break your build:

pickFiles() now returns List<PlatformFile> directly. The FilePickerResult wrapper is gone. An empty list means the user canceled.

// v11
FilePickerResult? result = await FilePicker.pickFiles();

// v12
List<PlatformFile> files = await FilePicker.pickFiles();

Single-file picking has its own method. pickFile() returns a PlatformFile?.

Reading bytes is explicit. The withData and withReadStream flags are removed. Read from the file object instead:

Uint8List bytes = await file.readAsBytes();
Stream<Uint8List> stream = file.readAsByteStream();

PlatformFile.size is gone — reading length is now a method, because on some platforms it means touching the disk. await file.length() replaced it.

Platform options are grouped. Scattered platform parameters are consolidated into AndroidOptions, DarwinOptions, WindowsOptions, LinuxOptions, and WebOptions — a direct consequence of the federated split, since each platform’s configuration now lives with its implementation.

The v13 follow-up

v13 tightened a few of those decisions rather than reshaping the architecture again:

• PlatformFile.length() returns Future<int?>. null now means the length could not be determined (for example, a failed disk read) — distinct from a genuinely empty file, which returns 0. A lengthSync() accessor was added for the case where the native picker already reported a size, so you can write file.lengthSync() ?? await file.length().
• Leftover v12-deprecated parameters were removed — allowMultiple, withData, withReadStream, readSequential on pickFiles(), plus lockParentWindow and cancelUploadOnWindowBlur, all of which had already been superseded by the grouped platform options.

The compatibility chart in the README is worth checking before you rely on a feature: pickFile/pickFiles/saveFile are supported across all six platforms, while getDirectoryPath is not available on web and clearTemporaryFiles is mobile-only. The Darwin implementation notes also flag that iOS requires 14.0+, because it uses PHPickerViewController.

The maintainer story

Beyond the code, file_picker has a human arc worth knowing. Miguel Ruivo wrote the first commit in June 2018 and maintained it for eight years — six platform implementations, hundreds of releases, millions of monthly downloads. Maintenance moved to a new repository in 2026. The new maintainers are explicit that the architecture, API, and hard problems were solved long before the transition; they are building on top of that foundation.

For a package this ubiquitous, a clean, acknowledged handoff — rather than silent abandonment — is the good outcome. If you depend on file_picker in production, it is worth confirming you are tracking the maintained repository’s releases.

Key takeaways

file_picker is now a federated plugin: a stable app-facing package over a platform interface and six per-platform implementations, which is what lets platforms ship independently. v12 replaced FilePickerResult with a direct List<PlatformFile>, split out pickFile(), made byte-reading explicit, and grouped platform options; v13 made length() nullable with a lengthSync() fast path and removed the last v12-deprecated parameters. The package also changed maintainers in 2026 after eight years under its original author — verify you are on the maintained line.

Further reading

• file_picker on pub.dev
• file_picker API reference
• Developing federated plugins