permission_handler 5.0.1+1

  • Readme
  • Changelog
  • Example
  • Installing
  • 100

pub package Build Status style: effective dart

On most operating systems, permissions aren't just granted to apps at install time. Rather, developers have to ask the user for permissions while the app is running.

This plugin provides a cross-platform (iOS, Android) API to request permissions and check their status. You can also open the device's app settings so users can grant a permission.
On Android, you can show a rationale for requesting a permission.

Setup #

While the permissions are being requested during runtime, you'll still need to tell the OS which permissions your app might potentially use. That requires adding permission configuration to Android- and iOS-specific files.


Upgrade pre 1.12 Android projects

Since version 4.4.0 this plugin is implemented using the Flutter 1.12 Android plugin APIs. Unfortunately this means App developers also need to migrate their Apps to support the new Android infrastructure. You can do so by following the Upgrading pre 1.12 Android projects migration guide. Failing to do so might result in unexpected behaviour. Most common known error is the permission_handler not returning after calling the .request() method on a permission.


As of version 3.1.0 the permission_handler plugin switched to the AndroidX version of the Android Support Libraries. This means you need to make sure your Android project is also upgraded to support AndroidX. Detailed instructions can be found here.

The TL;DR version is:

  1. Add the following to your "" file:
  1. Make sure you set the compileSdkVersion in your "android/app/build.gradle" file to 28:
android {
  compileSdkVersion 28
  1. Make sure you replace all the android. dependencies to their AndroidX counterparts (a full list can be found here:

Add permissions to your AndroidManifest.xml file. There's a debug, main and profile version which are chosen depending on how you start your app. In general, it's sufficient to add permission only to the main version. Here's an example AndroidManifest.xml with a complete list of all possible permissions.


Add permission to your Info.plist file. Here's an example Info.plist with a complete list of all possible permissions.

IMPORTANT: You will have to include all permission options when you want to submit your App. This is because the permission_handler plugin touches all different SDKs and because the static code analyser (run by Apple upon App submission) detects this and will assert if it cannot find a matching permission option in the Info.plist. More information about this can be found here.

The permission_handler plugin use macros to control whether a permission is supported.

You can remove permissions you don't use:

  1. Add the following to your Podfile file:
    post_install do |installer|
      installer.pods_project.targets.each do |target|
        target.build_configurations.each do |config|
          ... # Here are some configurations automatically generated by flutter
          # You can remove unused permissions here
          # for more infomation:
          # e.g. when you don't need camera permission, just add 'PERMISSION_CAMERA=0'
          config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
            ## dart: PermissionGroup.calendar
            # 'PERMISSION_EVENTS=0',
            ## dart: PermissionGroup.reminders
            # 'PERMISSION_REMINDERS=0',
            ## dart: PermissionGroup.contacts
            # 'PERMISSION_CONTACTS=0',
            ## dart:
            # 'PERMISSION_CAMERA=0',
            ## dart: PermissionGroup.microphone
            # 'PERMISSION_MICROPHONE=0',
            ## dart: PermissionGroup.speech
            ## dart:
            # 'PERMISSION_PHOTOS=0',
            ## dart: [PermissionGroup.location, PermissionGroup.locationAlways, PermissionGroup.locationWhenInUse]
            # 'PERMISSION_LOCATION=0',
            ## dart: PermissionGroup.notification
            ## dart: PermissionGroup.mediaLibrary
            ## dart: PermissionGroup.sensors
            # 'PERMISSION_SENSORS=0'
  2. Remove the # character in front of the permission you do not want to use. For example if you don't need access to the calendar make sure the code looks like this:
            ## dart: PermissionGroup.calendar
  3. Delete the corresponding permission description in Info.plist e.g. when you don't need camera permission, just delete 'NSCameraUsageDescription' The following lists the relationship between Permission and The key of Info.plist: | Permission | Info.plist | Macro | | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------- | | PermissionGroup.calendar | NSCalendarsUsageDescription | PERMISSION_EVENTS | | PermissionGroup.reminders | NSRemindersUsageDescription | PERMISSION_REMINDERS | | PermissionGroup.contacts | NSContactsUsageDescription | PERMISSION_CONTACTS | | | NSCameraUsageDescription | PERMISSION_CAMERA | | PermissionGroup.microphone | NSMicrophoneUsageDescription | PERMISSION_MICROPHONE | | PermissionGroup.speech | NSSpeechRecognitionUsageDescription | PERMISSION_SPEECH_RECOGNIZER | | | NSPhotoLibraryUsageDescription | PERMISSION_PHOTOS | | PermissionGroup.location, PermissionGroup.locationAlways, PermissionGroup.locationWhenInUse | NSLocationUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, NSLocationWhenInUseUsageDescription | PERMISSION_LOCATION | | PermissionGroup.notification | PermissionGroupNotification | PERMISSION_NOTIFICATIONS | | PermissionGroup.mediaLibrary | NSAppleMusicUsageDescription, kTCCServiceMediaLibrary | PERMISSION_MEDIA_LIBRARY | | PermissionGroup.sensors | NSMotionUsageDescription | PERMISSION_SENSORS |
  4. Clean & Rebuild

How to use #

There are a number of Permissions. You can get a Permission's status, which is either undetermined, granted, denied, restricted or permanentlyDenied.

var status = await;
if (status.isUndetermined) {
  // We didn't ask for permission yet.

// You can can also directly ask the permission about its status.
if (await Permission.location.isRestricted) {
  // The OS restricts access, for example because of parental controls.

Call request() on a Permission to request it. If it has already been granted before, nothing happens.
request() returns the new status of the Permission.

if (await Permission.contacts.request().isGranted) {
  // Either the permission was already granted before or the user just granted it.

// You can request multiple permissions at once.
Map<Permission, PermissionStatus> statuses = await [

Some permissions, for example location or acceleration sensor permissions, have an associated service, which can be enabled or disabled.

if (await Permission.locationWhenInUse.serviceStatus.isEnabled) {
  // Use location.

You can also open the app settings:

if (await Permission.speech.isPermanentlyDenied) {
  // The user opted to never again see the permission request dialog for this
  // app. The only way to change the permission's status now is to let the
  // user manually enable it in the system settings.

On Android, you can show a rationale for using a permission:

bool isShown = await Permission.contacts.shouldShowRequestRationale;

Issues #

Please file any issues, bugs or feature request as an issue on our GitHub page.

Want to contribute #

If you would like to contribute to the plugin (e.g. by improving the documentation, solving a bug or adding a cool new feature), please carefully review our contribution guide and send us your pull request.

Author #

This Permission handler plugin for Flutter is developed by Baseflow. You can contact us at

5.0.1+1 #

  • Fixes Typo
  • Issue #233 - on 5.0: Solved a bug that prevented Android applications running in the background to check the permission status.

5.0.1 #

  • Update permission_handler_platform_interface 2.0.1

5.0.0+hotfix.10 #

  • Revert pull-request #317

5.0.0+hotfix.9 #

  • Solved an issue where kCLAuthorizationStatusAuthorizedWhenInUse was returning PermissionStatusDenied (see #317)

5.0.0+hotfix.8 #

  • Solved an issue on iOS where requesting notifcation permissions returned prematurely (see pull-request #297)

5.0.0+hotfix.7 #

  • ** Mistake release please don't use this version **

5.0.0+hotfix.6 #

  • Solved an issue on iOS where requesting notification permissions always resulted in a "granted" result (see pull-request #289)

5.0.0+hotfix.5 #

  • Remove use of the deprecated pre iOS 8 API causing users compile issues (see issue #277).

5.0.0+hotfix.4 #

  • Solve issue on Android causing an IllegalStateException (#267).

5.0.0+hotfix.3 #

  • Includes the changes of 4.4.0+hotfix.4 (which was released to be backwardscompatible).

5.0.0+hotfix.2 #

  • Removed some residual usages of the PermissionStatusUnknown constants in #ifdef statements that were not found by the compiler.

5.0.0+hotfix.1 #

  • Make sure all enums from permission_handler_platform_interface: 2.0.0 are exposed through the permission_handler.

5.0.0 #

  • BREAKING: Implemented more intuitive API exposed by permission_handler_platform_interface: 2.0.0 (#230).

4.4.0+hotfix.4 #

  • Android: solved issue where permission_handler is used in a service (see #251)

4.4.0+hotfix.3 #

IGNORE THIS VERSION, it was released by accident and contains the same code as 4.4.0+hotfix.2

4.4.0+hotfix.2 #

  • Issue #235: Solved a bug which made it impossible to request service status on Android 7;
  • Issue #237: Solved a bug which crashes the application when cancelling the "Ignore battery optimizations" request for permissions.

4.4.0+hotfix.1 #

  • Issue #233: Solved a bug that prevented Android applications running in the background to check the permission status.

4.4.0 #

  • Updated plugin structure to confirm to the Flutter federated plugin architecture. This will make it easier to add new platform implementations (see:;
  • Android: Migrate to FlutterPlugin Android API (better support for Add-to-App);
  • Android: Suppress JAVA warnings which are generated to old platform code (only executes on older platforms);
  • Android: Fixed issue which sometimes resulting in illegal cast exception.

4.3.0 #

  • Allow requesting location permissions when location services are disabled (on iOS this will redirect the user to the Location settings page);
  • Android: Add support for requesting Activity Recognition permissions;
  • Confirm to Effective Dart guidelines;
  • Documented all public API members;
  • Fixed several typos in the

4.2.0+hotfix.3 #

  • Android: Fixes a bug which in some cases caused the permission neverAskAgain to be returned incorrectly.

4.2.0+hotfix.2 #

  • Android: Fixes a bug where permissions are reported as neverAskAgain incorrectly after calling requestPermissions method.

4.2.0+hotfix.1 #

  • Android: Fixes a bug where permissions are reported as neverAskAgain incorrectly.

4.2.0 #

  • Android: Methods checkPermissionStatus and requestPermissions now support addition neverAskAgain status.

4.1.0 #

  • iOS: Added option to exclude permissions logic using macros. This allows developers to submit their app to the AppStore without having to include all permissions in their Info.plist;
  • Android: Support ANSWER_PHONE_CALLS permission for API 26 and higher;
  • Android: Support ACCESS_MEDIA_LOCATION permission for API 26 and higher;
  • Android: Synchronized Gradle version with Flutter stable (1.12.13+hotfix.5).

4.0.0 #

  • iOS: Added support for requesting permissions on the DOCUMENTS and DOWNLOADS folder (thanks to @phranck);
  • Androis: Fix the PROCESS_OUTGOING_CALLS permissions which have been deprecated in API 29.

3.3.0 #

  • Android: Add support for requesting the background location permission within the locationAlways group.
  • Android: Update AGP, Gradle and AndroidX dependencies

3.2.2 #

  • Fixed problem with dependency on specific version of gradle wrapper on Android.

3.2.1+1 #

  • Reverted the update of the 'meta' plugin since Flutter SDK depends on version 1.1.6

3.2.1 #

  • Updated dependecy on 'meta' to latest version.

3.2.0 #

  • Add support for Androids' "ignore battery optimizations" permission;
  • Improve error logging;
  • Documented support for AndroidX.

3.1.0 #

  • Support service status inquiry for phone permission on iOS & Android.

3.0.2 #

  • Fixed bug when rapidly requesting permissions (#23);
  • Rename Enums.h to PermissionHandlerEnums.h to prevent conflicts with geolocator (#104);
  • Update the Android permission request code to prevent conflicts with geolocator (#111);
  • Update Gradle infrastructure.

3.0.1 #

  • Mark the Swift pod as static

3.0.0 #

  • Converted the iOS version from Swift to Objective-C, reducing the size of the final binary considerably.

2.2.0 #

  • Added new method checkServiceStatus to allow users to check if the location services (on Android and iOS) and motion services (iOS only) are enabled;
  • When checking permission status (using checkPermissionStatus) return PermissionStatus.disabled when permissions are granted or denied and the location services (on Android and iOS) or the motion services (iOS only) are disabled.

2.1.3 #

  • Fixed bug on iOS where result of the openAppSettings call always returned false;
  • Upgrade Android plugin to support AndroidX and latest Gradle and Kotlin versions;
  • Added Swift version number to the Podfile of the plugin;
  • Updated flutter static analyzes to conform to latest recommendations.

2.1.2 #

  • Make sure the Permission Handler compiles with latest iOS SDK

2.1.1 #

  • Update to the latest version of Swift (4.2);
  • Make sure that the correct Swift version is set in the Podfile of consuming Apps;
  • Updated configuration for statis code analyses, so it complies with the Flutter recommendations.

2.1.0 #

  • Added Android support to check if location services are enabled. If location services are not running the permission check returns PermissionStatus.DISABLED.

2.0.1 #

  • Fix bug with dependency on library
  • Update used Kotlin and Gradle versions

2.0.0 #

  • Make methods non static so users can create an instance or override

1.0.1 #

  • Converted the plugin into a library so that developers don't have to import additional files;
  • Updated the to fix example code.

1.0.0 #

  • Initial release.


import 'dart:io';

import 'package:flutter/material.dart';
import 'package:permission_handler/permission_handler.dart';

void main() => runApp(MyApp());

/// Example Flutter Application demonstrating the functionality of the
/// Permission Handler plugin.
class MyApp extends StatelessWidget {
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Plugin example app'),
          actions: <Widget>[
              icon: const Icon(Icons.settings),
              onPressed: () async {
                var hasOpened = openAppSettings();
                debugPrint('App Settings opened: ' + hasOpened.toString());
        body: Center(
          child: ListView(
              children: Permission.values
                  .where((Permission permission) {
                    if (Platform.isIOS) {
                      return permission != Permission.unknown &&
                          permission != Permission.sms &&
                          //permission != &&
                          permission != Permission.ignoreBatteryOptimizations &&
                          permission != Permission.accessMediaLocation;
                    } else {
                      return permission != Permission.unknown &&
                          permission != Permission.mediaLibrary &&
                          permission != &&
                          permission != Permission.reminders;
                  .map((permission) => PermissionWidget(permission))

/// Permission widget which displays a permission and allows users to request
/// the permissions.
class PermissionWidget extends StatefulWidget {
  /// Constructs a [PermissionWidget] for the supplied [Permission].
  const PermissionWidget(this._permission);

  final Permission _permission;

  _PermissionState createState() => _PermissionState(_permission);

class _PermissionState extends State<PermissionWidget> {

  final Permission _permission;
  PermissionStatus _permissionStatus = PermissionStatus.undetermined;

  void initState() {


  void _listenForPermissionStatus() async {
    final status = await _permission.status;
    setState(() => _permissionStatus = status);

  Color getPermissionColor() {
    switch (_permissionStatus) {
      case PermissionStatus.denied:
      case PermissionStatus.granted:
        return Colors.grey;

  Widget build(BuildContext context) {
    return ListTile(
      title: Text(_permission.toString()),
      subtitle: Text(
        style: TextStyle(color: getPermissionColor()),
      trailing: IconButton(
          icon: const Icon(,
          onPressed: () {
            checkServiceStatus(context, _permission);
      onTap: () {

  void checkServiceStatus(BuildContext context, Permission permission) async {
      content: Text((await permission.status).toString()),

  Future<void> requestPermission(Permission permission) async {
    final status = await permission.request();

    setState(() {
      _permissionStatus = status;

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  permission_handler: ^5.0.1+1

2. Install it

You can install packages from the command line:

with Flutter:

$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:permission_handler/permission_handler.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Jul 11, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.14
  • Flutter: 1.17.5

Analysis suggestions

Package does not support Flutter platform linux


  • package:permission_handler/permission_handler.dart that declares support for platforms: android, ios

Package does not support Flutter platform macos


  • package:permission_handler/permission_handler.dart that declares support for platforms: android, ios

Package does not support Flutter platform web


  • package:permission_handler/permission_handler.dart that declares support for platforms: android, ios

Package does not support Flutter platform windows


  • package:permission_handler/permission_handler.dart that declares support for platforms: android, ios

Package not compatible with SDK dart


  • permission_handler that is a package requiring null.

Health suggestions

Format lib/permission_handler.dart.

Run flutter format to format lib/permission_handler.dart.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
flutter 0.0.0
meta ^1.1.6 1.1.8 1.2.2
permission_handler_platform_interface ^2.0.1 2.0.1
Transitive dependencies
collection 1.14.12 1.14.13
sky_engine 0.0.99
typed_data 1.1.6 1.2.0
vector_math 2.0.8 2.1.0-nullsafety
Dev dependencies
effective_dart ^1.2.1
plugin_platform_interface ^1.0.1 1.0.2