FileSaver #

Huge Shoutout to all the contributors and the people who are using this package, I'm really grateful to all of you. Thank you for your support. #

This plugin package primarily focuses on one task: saving files on Android, iOS, Web, Windows, MacOS, and Linux. It might not have a plethora of features, but it does this job well. This package depends on path_provider for Android and iOS, browser download APIs for Web, and platform file APIs for desktop. The main reason I built this plugin was to avoid using HTML just for downloading files. The plugin is pretty simple and saves the file in Downloads folder in Windows, MacOS, Linux and directly downloads the file in Web, in iOS, the file is Saved in Application Documents Directory, and in Android it is saved in the applications files directory Android/data/your.package.name/file/your_file.extension.

Getting Started #

The plugin itself is pretty easy to use. Just call the method saveFile() with respective arguments.

await FileSaver.instance.saveFile({
      required String name,
      Uint8List? bytes,
      File? file,
      String? filePath,
      LinkDetails? link,
      String fileExtension = "",
      bool includeExtension = true,
      MimeType mimeType = MimeType.other,
      String? customMimeType,
      http.Client? httpClient,
});

This saveFile() method has 9 Named arguments.

String name which takes the name of the file,
Uint8List bytes which will be your actual encoded file,
Or
File file which will be your file in the File object (from dart:io)
Or
Stirng filePath which will be your file path
Or
LinkDetails link which will provide the link, header, request methid and body to your file. LinkDetails can be used as

LinkDetails(
      link: "https://www.example.com/file.extentions",
      headers: {"your-header-key": "you-header-value"},
      method: "POST",
      body: body
)

Out of these parameters, you will have to use atleast one

String fileExtension this will be your file extension.
bool includeExtension this controls whether to include the extension in the saved file name. Set to false to save files without extension (e.g., "myfile" instead of "myfile.txt"). Defaults to true.
Another parameter is MimeType type Specifically for Web, which will be your file type

String customMimeType this will be your custom mime type, if you want to use your own mime type, you can use this parameter

http.Client httpClient optional package:http client used when downloading from link. Pass your own for proxies, retries, cookies or logging; otherwise a client is created and closed per call

MimeType is also included in my Package, I've included types for Sheets, Presentation, Word, Plain Text, PDF, MP3, MP4 and many other common formats

or you can call saveAs() available for Android, iOS, macOS, Windows, and Web

await FileSaver.instance.saveAs({
      required String name,
      Uint8List? bytes,
      File? file,
      String? filePath,
      LinkDetails? link,
      String fileExtension = "",
      bool includeExtension = true,
      required MimeType mimeType,
      String? customMimeType,
      String? initialDirectory,
      String? dialogTitle,
      http.Client? httpClient,
});

All the parameters in this method is same as the saveFile() method, plus two dialog options (also accepted by saveAsStream and saveLinkAsStream):

Both are ignored on platforms that don't support them, so it's safe to pass them unconditionally.

Save to the gallery #

saveToGallery puts an image or video into the device's photo library without showing a dialog. Android and iOS only; other platforms throw UnsupportedError.

await FileSaver.instance.saveToGallery(
  name: "holiday",
  bytes: pngBytes,          // or file / filePath / link
  fileExtension: "png",
  mimeType: MimeType.png,   // must be an image/* or video/* type
  album: "My App",          // optional
);

Returns the MediaStore content URI on Android and the PHAsset local identifier on iOS.

• Android 10+: no permission needed. Files land in Pictures/<album> or Movies/<album>.
• Android 9 and below: your app must hold WRITE_EXTERNAL_STORAGE at runtime. The plugin already declares it with maxSdkVersion="28".
• iOS: add NSPhotoLibraryAddUsageDescription to Info.plist. Passing album also needs NSPhotoLibraryUsageDescription, because finding or creating an album requires read access to the library.

For very large direct URL downloads, prefer handing the URL to the browser on web or Android DownloadManager so the app does not fetch the full file into memory:

await FileSaver.instance.downloadLink(
  link: LinkDetails(link: "https://example.com/large-file.zip"),
  name: "large-file.zip",
);

downloadLink is a browser/system handoff. On Web it cannot attach custom headers such as Authorization. Browser-managed cookies may be sent only if the URL and cookie policy allow it. On Android, downloadLink uses DownloadManager and can pass request headers.

For authenticated large downloads on Web, use saveLinkAsStream. It uses fetch, so request headers and browser-managed credentials can be included, then it streams the response into a user-selected file:

await FileSaver.instance.saveLinkAsStream(
  name: "private-export",
  link: LinkDetails(
    link: "https://example.com/private/export.zip",
    headers: {"Authorization": "Bearer token"},
  ),
  fileExtension: "zip",
  includeCredentials: true,
);

This Web path requires the File System Access API and CORS permission from the server. JavaScript cannot manually set the Cookie header; use normal browser session cookies, a signed URL, or an Authorization header instead.

For native platforms, prefer filePath/file or saveAsStream for large generated content so the final save step can stream/copy from disk. On Web, saveAsStream uses the File System Access API where the browser supports it:

await FileSaver.instance.saveAsStream(
  name: "large-export",
  stream: myByteStream,
  fileExtension: "zip",
  mimeType: MimeType.zip,
);

Large files on Web #

Web has different behavior depending on where the data comes from:

Firefox/Mozilla and Safari do not currently provide the writable File System Access API needed by saveAsStream. For very large files in those browsers, use downloadLink with a direct server/CDN/S3 URL so the browser download manager streams the file to disk. Avoid passing multi-GB Uint8List values to saveFile/saveAs on Web because that path must create a Blob in memory.

Note: customMimeType can only be used when mimeType is set to MimeType.custom #

Usage Examples: #

Save file with extension (default behavior):

await FileSaver.instance.saveFile(
  name: "my_document",
  bytes: fileBytes,
  fileExtension: "pdf",
  mimeType: MimeType.pdf,
);
// Saves as: my_document.pdf

Save file without extension:

await FileSaver.instance.saveFile(
  name: "my_document",
  bytes: fileBytes,
  fileExtension: "pdf",
  includeExtension: false,
  mimeType: MimeType.pdf,
);
// Saves as: my_document

Save file from URL without extension:

await FileSaver.instance.saveFile(
  name: "downloaded_file",
  link: LinkDetails(link: "https://example.com/file.pdf"),
  fileExtension: "pdf",
  includeExtension: false,
  mimeType: MimeType.pdf,
);
// Saves as: downloaded_file

Storage Permissions & Network Permissions: #

These Settings are optional for iOS, as in iOS the file will be saved in application documents directory but will not be visible in Files application, to make your file visible in iOS Files application, make the changes mentioned below.

iOS:

Go to your project folder, ios/Runner/info.plist and Add these keys:

<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>
<key>UIFileSharingEnabled</key>
<true/>

Or in XCode:

Open Your Project in XCode (Open XCode -> Open a project or file -> Your_Project_Folder/ios/Runner.xcworkspace) Open info.plist Add these rows:

Application supports iTunes file sharing (Boolean -> Yes)

Supports opening documents in place (Boolean -> Yes)

macOS:

Go to your project folder, macOS/Runner/DebugProfile.entitlements

For release you need to open 'YOUR_PROJECT_NAME'Profile.entitlements

and add the following key:

<key>com.apple.security.files.downloads.read-write</key>
<true/>

Or in XCode:

Open Your Project in XCode (Open XCode -> Open a project or file -> Your_Project_Folder/macos/Runner.xcworkspace) Open your entitlement file (DebugProfile.entitlements & 'YOUR_PROJECT_NAME'Profile.entitlements)

Add these rows:

and if you get Client Socket Exception while saving files in MacOS from link, you have to add this key in the DebugProfile.entitlements and Release.entitlements of your macOS application and set the value to true

<key>com.apple.security.network.client</key>
<true/>

You can find these files in the project_folder/macos/Runner/ directory.

Which entitlements file? The Flutter template ships DebugProfile.entitlements (used by Debug and Profile builds) and Release.entitlements. If your project has renamed build configurations, the files may be called something like RunnerDebug.entitlements / RunnerRelease.entitlements instead. To be sure, open the Runner target in Xcode → Build Settings → Code Signing Entitlements and edit whichever file is listed for each configuration.

Windows:

No extra setup. The plugin only uses the Win32 GetSaveFileName API from Commdlg.h, so it has no SDK requirement beyond what Flutter desktop itself needs (Visual Studio 2022 with the Desktop development with C++ workload, which includes the Windows 10 SDK). Windows 10 or newer is required at runtime, same as Flutter.

And You're done

Thank You For Reading this far :) #

Contributors #