Photo Library Permission — basics, access types and working principle

Photo Library Permission Basics

Photo Library Permission is a system permission that regulates an app's access to media files stored on the device. It covers both reading (viewing and selecting photos and videos) and writing (saving new files to the gallery). Mobile platforms consider the media library as sensitive data because photos may contain personal and private information.

On Android 13 (API 33), Google split the single READ_EXTERNAL_STORAGE permission into three separate ones: READ_MEDIA_IMAGES for photos, READ_MEDIA_VIDEO for videos, and READ_MEDIA_AUDIO for audio. This allows users to grant access only to a specific type of media file. On iOS, starting with iOS 14, PhotoKit enables users to select specific photos for access rather than opening the entire library.

According to Counterpoint Research (2024), more than 70% of mobile apps in the categories of social networks, communication, and photo editors request Photo Library Permission. At the same time, 32% of users deny gallery access if they do not understand why the app needs their photos. Apple and Google recommend using the system PhotoPicker for selecting individual files without requesting full access.

Gallery Access on Android

Gallery access on Android has changed significantly with the release of Android 13. Instead of a single READ_EXTERNAL_STORAGE permission, granular permissions for each media type have been introduced, giving users more control.

Permissions on Android 13+

Starting with Android 13, READ_MEDIA_IMAGES is used for photo access, READ_MEDIA_VIDEO for video access. The READ_EXTERNAL_STORAGE permission no longer provides access to media files — it is retained only for reading non-media files from shared storage. The manifest declaration looks like this:

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

Compatibility with Android 12 and Below

For backward compatibility with Android 12 and below, you also need to declare READ_EXTERNAL_STORAGE. However, Android 13 automatically ignores this permission when the new granular ones are present. Use the android:maxSdkVersion="32" attribute in the manifest for the old permission to hide it on newer versions. This prevents redundant requests on devices running Android 13+.

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" />

Runtime Request in Kotlin

Runtime request for Photo Library Permission on Android is performed via the Activity Result API. Example for requesting image access:

private val photoPermissionLauncher =
    registerForActivityResult(ActivityResultContracts.RequestPermission()) { granted ->
    if (granted) {
        loadGalleryImages()
    } else {
        showPermissionDenied()
    }
}

fun pickPhoto() {
    val permission = if (Build.version.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        Manifest.permission.READ_MEDIA_IMAGES
    } else {
        Manifest.permission.READ_EXTERNAL_STORAGE
    }
    if (ContextCompat.checkSelfPermission(this, permission)
        == PackageManager.PERMISSION_GRANTED) {
        loadGalleryImages()
    } else {
        photoPermissionLauncher.launch(permission)
    }
}

Gallery Access on iOS

Gallery access on iOS is managed through the PhotoKit framework and the NSPhotoLibraryUsageDescription and NSPhotoLibraryAddUsageDescription keys in Info.plist. Starting with iOS 14, users can grant access only to selected photos (Limited Photo Library).

Info.plist Configuration

Reading photos from the library requires NSPhotoLibraryUsageDescription, while writing (saving photos) requires NSPhotoLibraryAddUsageDescription. If the app only saves media but does not read it, the second key is sufficient.

<key>NSPhotoLibraryUsageDescription</key>
<string>The app needs access to photos to select a profile picture and publish snapshots.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>The app needs access to save processed photos to your gallery.</string>

Request in Swift

Photo access request on iOS is performed via PHPhotoLibrary.requestAuthorization. Starting with iOS 14, the .limited status indicates that the user has granted access to a limited set of photos.

import PhotosUI

func requestPhotoLibraryAccess() {
    PHPhotoLibrary.requestAuthorization { status in
        DispatchQueue.main.async {
            switch status {
            case .authorized:
                self.loadPhotoLibrary()
            case .limited:
                self.loadSelectedPhotos()
            case .denied, .restricted:
                self.showSettingsAlert()
            case .notDetermined:
                break
            }
        }
    }
}

private func loadPhotoLibrary() {
    let fetchOptions = PHFetchOptions()
    fetchOptions.sortDescriptors = [NSSortDescriptor(key: "creationDate", ascending: false)]
    let assets = PHAsset.fetchAssets(with: .image, options: fetchOptions)
    // Handling request results
}

Handling Limited Access

The .limited status on iOS 14+ means the user has granted access only to a few selected photos. The app can request extended access through a system dialog by calling PHPhotoLibrary.shared().presentLimitedLibraryPicker. It is recommended to show this dialog only when the user explicitly requests a feature that requires additional photos.

PhotoPicker vs System Permission

PhotoPicker is a system component for selecting media files that does not require permission to access the entire library. Starting with Android 13 and iOS 14, Google and Apple recommend using PhotoPicker instead of requesting Photo Library Permission if the app only needs to select one or several photos.

PhotoPicker on Android

On Android 13+, the built-in PhotoPicker (ActivityResultContracts.PickVisualMedia) allows users to select a photo or video without granting access to the entire gallery. The app receives only the URI of the selected files. PhotoPicker works without declaring any permissions in the manifest.

private val pickMedia =
    registerForActivityResult(ActivityResultContracts.PickVisualMedia()) { uri ->
    if (uri != null) {
        // URI of the selected file, without access to the entire library
        showImage(uri)
    }
}

fun selectPhoto() {
    pickMedia.launch(PickVisualMediaRequest(ActivityResultContracts.PickVisualMedia.ImageOnly))
}

PHPicker on iOS

On iOS 14+, PHPickerViewController was introduced — a system picker that also does not require access to the entire library. PHPicker runs in a separate process and has no access to the app's library. This is the preferred way to select photos for most scenarios.

import PhotosUI

func presentPhotoPicker() {
    var config = PHPickerConfiguration()
    config.selectionLimit = 1
    config.filter = .images

    let picker = PHPickerViewController(configuration: config)
    picker.delegate = self
    present(picker, animated: true)
}

When Full Permission Is Needed

PhotoPicker is not suitable if the app needs access to the entire library for bulk operations: backup, cloud synchronization, gallery app, file manager. In these cases, you need to request Photo Library Permission and handle the limited access case (Limited). For iOS, you must include handling for the .limited status and offer users the option to extend access.

Best Practices for Gallery Access

Best practices for working with Photo Library Permission help reduce the number of denials and comply with platform privacy requirements.

Use PhotoPicker by Default

For selecting one or multiple photos, use the system PhotoPicker or PHPicker. These components do not require permissions and provide the best user experience. Request full gallery access only if the app's functionality requires access to the entire media library. Google and Apple explicitly recommend this approach in their developer documentation.

Explain the Reason for Full Access

If the app truly needs full gallery access, show a preliminary screen with an explanation. Explain why all photos are needed rather than just one. For example, a backup app should explain that it will scan all media files to create a copy. The pre-permission screen is especially important for iOS due to the Limited Access mechanism.

Request Only Necessary Permissions

If the app only saves photos but does not read them (e.g., a photo editor that saves the result), request only write permission to the gallery. On Android, this is WRITE_EXTERNAL_STORAGE (for Android 12 and below) or the MediaStore API without permissions (for Android 10+). On iOS, use NSPhotoLibraryAddUsageDescription without NSPhotoLibraryUsageDescription.