Google Drive Picker

google_drive_picker is a modern Flutter file picker for browsing, searching, and downloading files from a user's Google Drive.

The package uses Google Sign-In 7 and OAuth directly. It does not require Firebase Authentication or a Google API key.

Features

  • Read-only Google Drive OAuth authorization
  • Paginated listing across My Drive and Shared Drives
  • Thumbnail previews with list/grid views and file-type filters
  • Search, adaptive download confirmation, loading, empty, and error states
  • Google Drive shortcut resolution and download-permission checks
  • Blob-file downloads and Google Workspace exports:
    • Google Docs → .docx
    • Google Sheets → .xlsx
    • Google Slides → .pptx
    • Google Drawings → .png
  • Sanitized filenames and temporary-file storage
  • Typed service errors and automatic HTTP client cleanup

Requirements

Requirement Minimum
Flutter 3.29
Dart 3.7
Android SDK 21
iOS 12.0
macOS 10.15

The current API returns a dart:io File; web is not supported.

Install

dependencies:
  google_drive_picker: ^1.0.0

Then run:

flutter pub get

Values you need

Create these values in the Google Cloud console. OAuth client IDs are public identifiers, not secrets.

Target Create in Google Auth Platform Used by the app
Android Android OAuth client Registered remotely; not pasted into Dart
Android sign-in Web application OAuth client serverClientId / GOOGLE_SERVER_CLIENT_ID
iOS iOS OAuth client clientId / GIDClientID
iOS callback Reversed iOS client ID CFBundleURLTypes URL scheme
macOS iOS OAuth client using the macOS bundle ID Same client-ID and URL-scheme setup as iOS

You do not need:

  • A Google API key
  • A service-account key
  • Firebase Authentication
  • An OAuth client secret inside the Flutter application

Never embed a web OAuth client secret, service-account JSON, access token, or signing private key in the app or repository.

Google Cloud setup

1. Create or select a project

Open the Google Cloud project selector and create or select the project that will own the OAuth configuration.

Use separate development and production Cloud projects when you need isolated test users, consent settings, quotas, or credentials.

2. Enable the Google Drive API

Open APIs & Services → Library, search for Google Drive API, open it, and select Enable.

Direct page: Google Drive API

Enabling a Drive UI integration or Google Workspace Marketplace listing is not required for this package.

3. Configure Google Auth Platform

Open Google Auth Platform for the selected project and complete:

  1. Branding — set the application name, support email, logo/domain details when applicable, and developer contact email.
  2. Audience — choose Internal for a supported Google Workspace organization-only app, or External for other Google accounts.
  3. Audience → Test users — while publishing status is Testing, add every Google account that should be allowed to sign in.
  4. Data Access → Add or remove scopes — add:
https://www.googleapis.com/auth/drive.readonly

This is the scope requested by the package. It permits viewing and downloading Drive files but not creating, editing, or deleting them.

Testing-mode authorization is intended for development and can expire, causing test users to be asked for consent again. Before public release, review the current Google OAuth verification and restricted-scope requirements.

4. Create OAuth clients

Open Google Auth Platform → Clients, select Create client, and create the platform clients described below.

Direct page: OAuth clients

Android configuration

Find the application ID

For the included example it is:

com.immichtv.google_drive_picker.example

For another app, read applicationId from android/app/build.gradle or android/app/build.gradle.kts. Use the exact value for the build variant being tested.

Generate signing fingerprints

From the Flutter application's android directory run:

./gradlew signingReport

On Windows use:

.\gradlew signingReport

Under the intended variant, copy its SHA-1 fingerprint. Register debug, release, and flavor-specific signing certificates separately when they differ. For a Play-distributed build using Play App Signing, also register the app signing certificate shown under Play Console → Setup → App integrity; it can differ from the upload certificate.

Create the Android OAuth client

In Google Auth Platform → Clients → Create client:

  1. Select Android.
  2. Enter a recognizable name.
  3. Enter the exact Android package/application ID.
  4. Enter the matching SHA-1 fingerprint.
  5. Create the client.

Repeat for any package-name/signing-certificate combination not covered by the first client.

Create the Web OAuth client used by Android

Create another client with application type Web application. Copy its client ID, which looks like:

123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com

Only the client ID is used. Do not put the generated client secret in Flutter.

Pass that web client ID to the example:

cd example
flutter run \
  --dart-define=GOOGLE_SERVER_CLIENT_ID=YOUR_WEB_OAUTH_CLIENT_ID

Alternatively, Android can obtain the web client ID through a properly configured google-services.json and Google Services Gradle integration. That route does not require Firebase Authentication, but it does require the normal Google Services setup. The --dart-define route is the smallest setup for this example.

iOS configuration

Find the bundle identifier

The included example uses:

com.example.example

For another app, open ios/Runner.xcodeproj in Xcode and inspect Runner target → Signing & Capabilities → Bundle Identifier, or inspect PRODUCT_BUNDLE_IDENTIFIER in the Xcode project.

Create the iOS OAuth client

In Google Auth Platform → Clients → Create client:

  1. Select iOS.
  2. Enter a recognizable name.
  3. Enter the exact bundle identifier.
  4. Create the client.
  5. Copy the normal client ID and the displayed iOS URL scheme. You can also download the configuration plist and read CLIENT_ID and REVERSED_CLIENT_ID.

Example normal client ID:

123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com

Corresponding reversed client ID / URL scheme:

com.googleusercontent.apps.123456789012-abcdefghijklmnopqrstuvwxyz

Add the URL scheme

Add the reversed OAuth client ID as a URL scheme in Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>YOUR_REVERSED_CLIENT_ID</string>
    </array>
  </dict>
</array>

For the example, replace YOUR_REVERSED_CLIENT_ID in example/ios/Runner/Info.plist.

Supply the normal iOS client ID

Choose either configuration method.

Method A — pass it when running the example:

cd example
flutter run \
  --dart-define=GOOGLE_CLIENT_ID=YOUR_IOS_OAUTH_CLIENT_ID

Method B — add it to ios/Runner/Info.plist:

<key>GIDClientID</key>
<string>YOUR_IOS_OAUTH_CLIENT_ID</string>

Then initialize without an explicit clientId. The reversed URL scheme is required for both methods so Google can return to the application after authentication.

macOS configuration

Create an iOS OAuth client using the macOS bundle identifier, then apply the same GIDClientID and reversed URL scheme configuration to macos/Runner/Info.plist.

Google Sign-In on macOS also requires keychain sharing. Add the access group required by the current google_sign_in_ios integration documentation to the Runner entitlements. This repository's example currently contains Android and iOS targets only.

Run the included example

Install packages:

flutter pub get
cd example
flutter pub get

List available devices:

flutter devices

Run Android:

flutter run \
  -d YOUR_ANDROID_DEVICE_ID \
  --dart-define=GOOGLE_SERVER_CLIENT_ID=YOUR_WEB_OAUTH_CLIENT_ID

Run iOS:

flutter run \
  -d YOUR_IOS_DEVICE_OR_SIMULATOR_ID \
  --dart-define=GOOGLE_CLIENT_ID=YOUR_IOS_OAUTH_CLIENT_ID

If identifiers are already supplied through native configuration, omit their corresponding --dart-define arguments.

Usage

Initialize once before runApp. Platform configuration can provide the client identifiers, so both arguments are optional:

import 'dart:io';

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

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await GoogleDrivePicker.instance.initialize(
    clientId: optionalIosClientId,
    serverClientId: optionalWebClientId,
  );

  runApp(const MyApp());
}

When supporting both Android and Apple platforms from one codebase, only pass the Apple client ID on iOS/macOS:

await GoogleDrivePicker.instance.initialize(
  clientId: (Platform.isIOS || Platform.isMacOS) ? iosClientId : null,
  serverClientId: webClientId,
);

The included example performs this platform check automatically for its GOOGLE_CLIENT_ID value.

Open the picker from a user interaction:

final File? file = await GoogleDrivePicker.instance.pickFile(
  context: context,
);

if (file != null) {
  // Open it, inspect it, or copy it to permanent application storage.
  debugPrint(file.path);
}

Sign out when your application needs to end the Google session:

await GoogleDrivePicker.instance.signOut();

File lifecycle

The returned file is written to the platform temporary directory. The operating system may delete it at any time. Copy it to application documents or other permanent storage if it must survive cache cleanup.

An existing temporary file with the same name may be replaced by a later download.

Errors and cancellation

  • Cancelling Google Sign-In or closing the picker returns null.
  • GoogleDriveAuthorizationException indicates that Drive authorization was not available.
  • GoogleDriveFileException covers unsupported exports, missing metadata, and files the user cannot download.
  • Other Google Sign-In, Drive API, network, and filesystem failures propagate to the caller.

Wrap picker calls in try/catch and present an appropriate retry action.

Production release checklist

  • Replace the sample package and bundle identifiers with identifiers owned by your application.
  • Use production OAuth clients that exactly match those identifiers.
  • Register Android debug, upload, and Play App Signing certificates as applicable.
  • Move the Google Auth Platform audience out of Testing when appropriate.
  • Complete brand/OAuth verification required for the selected audience and Drive scope.
  • Provide verified homepage, privacy-policy, and terms URLs when requested by Google Auth Platform.
  • Test release builds; debug credentials do not automatically authorize a differently signed release build.
  • Verify sign-in with an account that is not a project owner.
  • Review Drive API quotas and error reporting in the production Cloud project.
  • Never log authorization headers, access tokens, or downloaded user content.

Official configuration references

Migration and support

The deprecated setAPIKey method is a no-op retained only for short-term source compatibility. New code should not call it.