photo_manager

English | 中文

[][pub package]

A Flutter plugin that provides assets abstraction management APIs without UI integration, you can get assets (image/video/audio) on Android, iOS, macOS and OpenHarmony.

Projects using this plugin

name	pub	github
wechat_assets_picker
wechat_camera_picker

Articles about this plugin

• Hard to manage media with Flutter? Try photo_manager, the all-in-one solution

Migration guide

For versions upgrade across major versions, see the migration guide for detailed info.

• photo_manager
  • Projects using this plugin
  • Articles about this plugin
  • Migration guide
  • Common issues
  • Prepare for use
    • Add the plugin reference to pubspec.yaml
    • Import in your projects
    • Configure native platforms
      • Android config preparation
        • Kotlin, Gradle, AGP
        • Android 10 (Q, 29)
        • Glide
      • iOS config preparation
  • Usage
    • Request for permission
      • Limited entities access
        • Limited entities access on iOS
        • Limited entities access on Android
    • Get albums/folders (AssetPathEntity)
      • Params of getAssetPathList
      • PMPathFilterOption (Since 2.7.0)
    • Get assets ()

Common issues

Please search common issues in [GitHub issues][] for build errors, runtime exceptions, etc.

Prepare for use

Add the plugin reference to pubspec.yaml

Two ways to add the plugin to your pubspec:

• (Recommend) Run flutter pub add photo_manager.
• Add the plugin reference in your pubspec.yaml's dependencies section:

dependencies:
  photo_manager: $latest_version

The latest stable version is: [][pub package]

Import in your projects

import 'package:photo_manager/photo_manager.dart';

Configure native platforms

Minimum platform versions: Android 16, iOS 9.0, macOS 10.15.

• Android: Android config preparation.
• iOS: iOS config preparation.
• macOS: Pretty much the same with iOS.

Android config preparation

Kotlin, Gradle, AGP

We ship this plugin with Kotlin 1.7.22. If your projects use a lower version of Kotlin/Gradle/AGP, please upgrade them to a newer version.

More specifically:

• Upgrade your Gradle version (gradle-wrapper.properties) to 7.5.1 or the latest version.
• Upgrade your Kotlin version (ext.kotlin_version) to 1.7.22 or the latest version.
• Upgrade your AGP version (com.android.tools.build:gradle) to 7.2.2 or the latest version.

Android 10 (Q, 29)

If you're not setting your compileSdkVersion or targetSdkVersion to 29, you can skip this section.

On Android 10, Scoped Storage was introduced, which causes the origin resource file not directly inaccessible through it file path.

If your compileSdkVersion or targetSdkVersion is 29, you can consider adding android:requestLegacyExternalStorage="true" to your AndroidManifest.xml in order to obtain resources:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.fluttercandies.photo_manager_example">

    <application
        android:label="photo_manager_example"
        android:icon="@mipmap/ic_launcher"
        android:requestLegacyExternalStorage="true">
    </application>
</manifest>

Note: Apps that are using the flag will be rejected from the Google Play.

This is not a requirement, the plugin can still work with caching files. But you'll need to control caches on your own, the best practice is to clear file caches each time when you start your app by calling PhotoManager.clearFileCache().

Glide

The plugin use [Glide][] to create thumbnail bytes for Android.

If you found some warning logs with Glide appearing, it means the main project needs an implementation of AppGlideModule. See [Generated API][] for the implementation.

iOS config preparation

Define the NSPhotoLibraryUsageDescription key-value in the ios/Runner/Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>In order to access your photo library</string>

If you want to grant only write-access to the photo library on iOS 11 and above, define the NSPhotoLibraryAddUsageDescription key-value in the ios/Runner/Info.plist. It's pretty much the same as the NSPhotoLibraryUsageDescription.

Usage

Request for permission

Most of the APIs can only use with granted permission.

final PermissionState ps = await PhotoManager.requestPermissionExtend(); // the method can use optional param `permission`.
if (ps.isAuth) {
  // Granted
  // You can to get assets here.
} else if (ps.hasAccess) {
  // Access will continue, but the amount visible depends on the user's selection.
} else {
  // Limited(iOS) or Rejected, use `==` for more precise judgements.
  // You can call `PhotoManager.openSetting()` to open settings for further steps.
}

But if you're pretty sure your callers will be only called after the permission is granted, you can ignore permission checks:

PhotoManager.setIgnorePermissionCheck(true);

For background processing (such as when the app is not in the foreground), ignore permissions check would be proper solution.

You can also read the current permission state with PhotoManager.getPermissionState. Make sure the sa