photo_manager

The plugin uses a caching mechanism to handle file access across different platforms:

Android

• Android 10 (Q, 29): Direct access to resource paths is restricted. The plugin generates image caches during I/O operations (e.g., when calling .file or .originFile). You can use requestLegacyExternalStorage to access files without caching.
• Android 11+: Direct access to resource paths is available again.

iOS

• iOS does not provide an API to access original files directly. When calling .file or .originFile, the plugin generates a cache file within the application's sandbox.
• Important: If disk space is a concern, you should manually delete these cache files after use.

Clearing Cache

You can clear all plugin-generated caches using PhotoManager.clearFileCache.

import 'dart:io';

Future<void> useEntity(AssetEntity entity) async {
  File? file;
  try {
    file = await entity.file;
    await handleFile(file!); // 处理获取的文件
  } finally {
    if (Platform.isIOS) {
      file?.deleteSync(); // 处理完成后删除
    }
  }
}

The plugin generates local cache files when accessing I/O getters like entity.file or entity.originFile due to platform restrictions.

Android Cache

On Android 10, caches are generated during I/O. On Android 11+, resource paths can be accessed directly, but you can still use requestLegacyExternalStorage in your manifest to avoid caching.

iOS Cache

iOS requires a cached file to be generated in the application's container. If disk space is a concern, you should manually delete the file after use.

Clearing All Caches

You can clear all plugin-generated caches (thumbnails and files) using PhotoManager.clearFileCache().

import 'dart:io';

Future<void> useEntity(AssetEntity entity) async {
  File? file;
  try {
    file = await entity.file;
    await handleFile(file!); // Custom method to handle the obtained file.
  } finally {
    if (Platform.isIOS) {
      file?.deleteSync(); // Delete it once the process has done.
    }
  }
}

Both iOS 14+ and Android 14+ support a "Limited Photos Library" where users select only specific assets for the app to access.

iOS

• Use PhotoManager.presentLimited() to show a modal allowing users to manage/reselect accessible entities.
• To prevent the system from automatically prompting the user every time the app restarts, add the PHPhotoLibraryPreventAutomaticLimitedAccessAlert key to your Info.plist with a value of <true/>.

Android

• On Android 14, access to a specific resource cannot be revoked once granted, even if not selected via presentLimited in future actions.

Recovery from mismatched media types

If a user grants limited access but only selects videos when your app requested images, the query will return zero results. You should prompt for reselection using presentLimited with the specific RequestType needed.

if (state == PermissionState.limited) {
  // On Android 14+, `type` filters the picker to only the media kinds you need.
  // On iOS the picker cannot be filtered by type and `type` is ignored.
  await PhotoManager.presentLimited(type: RequestType.image);
}

Kotlin, Gradle, and AGP Requirements

The plugin requires Kotlin 1.7.22. If your project uses older versions, upgrade them to the following minimums:

• Gradle version (gradle-wrapper.properties): 7.5.1 or later.
• Kotlin version (ext.kotlin_version): 1.7.22 or later.
• AGP version (com.android.tools.build:gradle): 7.2.2 or later.

Android 10 (API 29) Scoped Storage

If your compileSdkVersion or targetSdkVersion is 29, you may need to add android:requestLegacyExternalStorage="true" to your AndroidManifest.xml to access origin resource files directly.

Warning: Apps using this flag may be rejected from Google Play. A better practice is to use the plugin's caching mechanism and call PhotoManager.clearFileCache() when starting your app.

Glide Thumbnails

The plugin uses [Glide] to generate thumbnail bytes on Android. If you see Glide warning logs, your main project may need to implement AppGlideModule.

<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>

In version 3.12, the Darwin implementation no longer links CoreLocation. Consequently, passing latitude or longitude to PhotoManager.editor.saveImage, saveImageWithPath, or saveVideo will throw an error.

To continue saving assets with location data on iOS/macOS, you must install and use the photo_manager_location plugin. Android remains unaffected.

Note: Apps that do not save assets with location no longer require the NSLocationWhenInUseUsageDescription purpose string.

import 'package:photo_manager_location/photo_manager_location.dart';

final entity = await PhotoManager.editor.saveImage(
  bytes,
  filename: 'photo.jpg',
  latitude: 37.7749,
  longitude: -122.4194,
);
// ^ This will throw on Darwin in 3.12+

// Use this instead:
final entity = await PhotoManagerLocation.editor.saveImage(
  bytes,
  filename: 'photo.jpg',
  latitude: 37.7749,
  longitude: -122.4194,
);

Depending on your target Android version, you must add specific permissions to your AndroidManifest.xml.

Android 14 (API 34)

Add the following for optional resource selection support:

<uses-permission android:name="android.permission.READ_MEDIA_VISUAL_USER_SELECTED" />

Android 13 (API 33)

Add these permissions to read images, videos, or audio:

<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />

Android 12 (API 31) - MANAGE_MEDIA (Optional)

To allow batch operations (like deleteWithIds, moveToTrash, or favorites) without repeated system confirmation dialogs, declare MANAGE_MEDIA. Users must manually enable this in system settings.

<uses-permission android:name="android.permission.MANAGE_MEDIA" />

Use PhotoManager.canManageMedia() to check status and PhotoManager.requestManageMedia() to direct users to settings.

Glide Version Conflicts

If you encounter Glide version conflicts, add this resolution strategy to your android/build.gradle:

rootProject.allprojects {
    subprojects {
        project.configurations.all {
            resolutionStrategy.eachDependency {
                if (details.requested.group == 'com.github.bumptech.glide' 
                        && details.requested.name.contains('glide')) {
                    details.useVersion '4.14.2'
                }
            }
        }
    }
}

<manifest>
   <uses-permission android:name="android.permission.READ_MEDIA_VISUAL_USER_SELECTED" />
</manifest>