Skip to main content

gal 3.0.1 copy "gal: ^3.0.1" to clipboard
gal: ^3.0.1 copied to clipboard

Flutter plugin to save images and videos to the photo gallery, with albums and permission handling.

Gal

Gal #

Save images and videos to the photo gallery with a single line of Dart.

Android · iOS · macOS · Windows

pub version pub points CI license Ask DeepWiki

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.

Like on pub.dev Star on GitHub Sponsor

✨ Highlights #

  • Simple API — Save with putImage, putVideo or putImageBytes. 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 hasPermission and requestPermission.
  • Metadata kept — EXIF and other metadata are saved along with the file.
  • Typed errors — Every failure is a GalException with a clear GalExceptionType.
  • 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
Gal on iOS Gal on 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.

Linux

Linux is not officially supported. Use the community plugin gal_linux.

💻 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 stars
Flutter Quill Rich text editor stars
Moodiary Diary app stars
Turms Instant messaging engine stars
Lotti Private logbook with AI assistants stars
Pho Photo sync to cloud storage stars
Stream Chat Chat SDK stars
Thunder Lemmy client stars

…and many more.


Released under the BSD 3-Clause License · Made with 💚 by @natsuk4ze
599
likes
160
points
733k
downloads

Documentation

Documentation
API reference

Publisher

verified publishermidoridesign.studio

Weekly Downloads

Flutter plugin to save images and videos to the photo gallery, with albums and permission handling.

Homepage
Repository (GitHub)
View/report issues
Contributing

Topics

#gallery #video #image #photos #util

Funding

Consider supporting this project:

github.com

License

BSD-3-Clause (license)

Dependencies

flutter

More

Packages that depend on gal

Packages that implement gal