gal 3.0.1
gal: ^3.0.1 copied to clipboard
Flutter plugin to save images and videos to the photo gallery, with albums and permission handling.
Gal #
Save images and videos to the photo gallery with a single line of Dart.
Android · iOS · macOS · Windows
pub.dev · API Reference · DeepWiki · Example · Q&A
import 'package:gal/gal.dart';
await Gal.putImage(path); // Save an image file
await Gal.putVideo(path); // Save a video file
await Gal.putImageBytes(bytes); // Save image bytes
await Gal.hasPermission(); // Check the permission
await Gal.requestPermission(); // Ask for the permission
💚 Support Gal #
Gal is built and maintained by volunteers.
If it saves you time, a like, a star or a sponsorship keeps it going.
✨ Highlights #
- Simple API — Save with
putImage,putVideoorputImageBytes. Each is a single static call. - Ultra-lightweight — No dependencies besides Flutter.
- Albums — Save to a named album. It is created if it does not exist.
- Permissions built in — Gal asks for access only when it needs it. Take control with
hasPermissionandrequestPermission. - Metadata kept — EXIF and other metadata are saved along with the file.
- Typed errors — Every failure is a
GalExceptionwith a clearGalExceptionType. - Easy to test — Replace the platform with a fake in your unit tests.
- Tested in CI — Integration tests run on Android, iOS, macOS and Windows.
📱 Platforms #
| Android | iOS | macOS | Windows | Linux | |
|---|---|---|---|---|---|
| Minimum | API 24 | 13 | 11 | 10 | gal_linux |
Every function is tested on each platform, automatically wherever possible.
Linux is available through gal_linux, a community plugin that is not officially endorsed.
📸 Demo #
| iOS | Android |
|---|---|
![]() |
![]() |
🚀 Getting Started #
1. Install #
flutter pub add gal
2. Set up each platform #
iOS
Add the following keys to ios/Runner/Info.plist:
<!-- Required -->
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Save photos and videos to your library.</string>
<!-- Required for iOS 13 or saving to an album -->
<key>NSPhotoLibraryUsageDescription</key>
<string>Save photos and videos to an album.</string>
See the example's Info.plist.
Android
Add the following to android/app/src/main/AndroidManifest.xml:
<!-- Required for API 29 and below -->
<uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE"
android:maxSdkVersion="29" />
<!-- Required for saving to an album on API 29 -->
<application android:requestLegacyExternalStorage="true">
See the example's AndroidManifest.xml.
⚠️ Android emulators with API below 29 need an SD card set up. Real devices don't.
macOS
Add the following keys to macos/Runner/Info.plist:
<!-- Required -->
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Save photos and videos to your library.</string>
<!-- Required for saving to an album -->
<key>NSPhotoLibraryUsageDescription</key>
<string>Save photos and videos to an album.</string>
See the example's Info.plist.
⚠️ Flutter has a known issue with loading Info.plist that can cause permission denials or crashes when running from some code editors.
Windows
Update Visual Studio to the latest version to build with C++20.
💡 If the build still fails, install the latest Windows SDK from Visual Studio Installer → Modify → Windows SDK.
💻 Usage #
Save images and videos #
// From a file. The path must include the extension.
await Gal.putImage('$filePath');
await Gal.putVideo('$filePath');
// From bytes. The extension is detected from the bytes.
await Gal.putImageBytes(bytes, name: 'photo');
// To an album. It is created if it does not exist.
await Gal.putImage('$filePath', album: 'My Album');
// Open the gallery app
await Gal.open();
Recipes #
Download from the internet
flutter pub add http
final bytes = await http.readBytes(Uri.parse('$url'));
await Gal.putImageBytes(bytes);
Take a photo
flutter pub add image_picker
final image = await ImagePicker().pickImage(source: ImageSource.camera);
if (image != null) await Gal.putImage(image.path);
Record a video
flutter pub add camera
await controller.startVideoRecording();
// ...
final video = await controller.stopVideoRecording();
await Gal.putVideo(video.path);
Permissions #
put methods ask for permission when the app does not have it yet, so you don't need to request it beforehand.
Request it yourself only to choose when the dialog appears, for example after showing your own explanation.
final hasPermission = await Gal.hasPermission();
final granted = await Gal.requestPermission();
// For saving to an album
await Gal.hasPermission(toAlbum: true);
await Gal.requestPermission(toAlbum: true);
Errors #
Every error is a GalException. Use its type to decide what to do.
try {
await Gal.putImage('$filePath');
} on GalException catch (e) {
log(e.type.message);
}
GalExceptionType |
When |
|---|---|
permissionDenied |
The app does not have permission to access the gallery. |
notEnoughSpace |
The device does not have enough storage. |
notSupportedFormat |
The OS does not support the file type or video codec. The path must include the extension. putImage and putVideo on Android and Windows do not look inside the file. |
unexpected |
Anything else. Please open an issue with platformException and stackTrace. |
Testing #
Gal calls native code, which does not run in unit tests or widget tests. In most cases, wrap Gal in your own class and mock that class.
To replace Gal itself, extend GalPlatform from package:gal/gal_platform_interface.dart and set it to GalPlatform.instance.
Methods that the fake does not override throw UnimplementedError.
import 'package:flutter_test/flutter_test.dart';
import 'package:gal/gal.dart';
import 'package:gal/gal_platform_interface.dart';
final class FakeGalPlatform extends GalPlatform {
@override
Future<void> putImage(String path, {String? album}) async {}
}
void main() {
setUp(() => GalPlatform.instance = FakeGalPlatform());
test('saves the image', () => Gal.putImage('image.jpg'));
}
📚 Resources #
- 🎯 Example — An app that uses every API
- 📖 API Reference — Documentation for every class and method
- 🧠 DeepWiki — How Gal works, explained by AI
- 💬 Q&A — Ask questions
- 💚 Contributing — How to send issues and PRs
Wrote an article about Gal? Let us know in Discussions and we'll link it here.
🤝 Trusted By #
| Project | About | Stars |
|---|---|---|
| LocalSend | Share files to nearby devices | |
| Flutter Quill | Rich text editor | |
| Moodiary | Diary app | |
| Turms | Instant messaging engine | |
| Lotti | Private logbook with AI assistants | |
| Pho | Photo sync to cloud storage | |
| Stream Chat | Chat SDK | |
| Thunder | Lemmy client |
…and many more.

