What is a file picker in Flutter?
File picking in Flutter app development allows users to select files from device storage such as PDFs, images, or documents. It is commonly used for uploads, attachments, and document handling features.
Flutter does not provide a built-in file picker, so this functionality is handled through plugins that integrate with native file systems.
How does it work?
A file picker opens the system file selection UI and returns metadata about the selected file. Depending on the platform, this may include file name, size, path, or access to the file content.
On mobile platforms, file access is mediated by the operating system. On Flutter Web, files are provided by the browser and do not expose real file paths.
Recommended package for file picking
The most widely used solution is the file_picker package.
It supports:
- Android, iOS, Web, and desktop
- single and multiple file selection
- file type filtering
- access to file metadata and content
For most Flutter apps, it covers all common file selection needs.
File picker example in Flutter
A minimal, production-safe example:
final result = await FilePicker.platform.pickFiles(
type: FileType.custom,
allowedExtensions: ['pdf', 'jpg', 'png'],
);
if (result == null) {
return;
}
final file = result.files.first;
// Mobile / desktop: access via path
if (file.path != null) {
final fileOnDisk = File(file.path!);
}
// Web or large files: avoid loading full bytes into memory
final stream = file.readStream;
For large files, reading data as a stream is recommended instead of using file.bytes, which loads the entire file into memory.
Handling large files safely
Using file.bytes for large files can cause memory issues, especially on low-end devices.
Best practices:
- Use
readStream for uploads. - Process data in chunks.
- Avoid loading entire files into RAM.
This is especially important for videos, PDFs, and multi-megabyte files.
File picker permissions in Flutter
On iOS, file permissions are handled automatically by the system file picker. No additional configuration is required in most cases.
On Android, modern versions of file_picker use the system file picker intent, which usually does not require manual storage permissions.
However, if your app needs access to files outside standard locations or requires persistent access to external storage, you may still need to:
- Verify storage-related permissions in
AndroidManifest.xml. - Test behavior on different Android versions and OEM devices.
In practice, file_picker works without extra permissions in most scenarios, but it is still worth validating this when working with external storage. On Flutter Web, permissions are entirely controlled by the browser.
File picker on Flutter Web
Flutter Web behaves differently than mobile:
file.path is usually null.- Files must be handled via streams or bytes.
- Large files require careful memory handling.
Sharing the same file logic across platforms without checks often leads to issues.
Common mistakes with file picker in Flutter
Typical beginner issues include:
- Loading large files using
bytes. - Assuming file paths exist on all platforms.
- Ignoring the cancel case.
- Reusing mobile file logic on web.
- Not testing storage access on Android devices.
Most file picker bugs appear during file processing, not during selection.
