---
title: Google Drive
description: Google Drive via the official Drive v3 client. Maps unified string keys onto Drive's appProperties with a per-instance LRU cache.
peerDeps:
  - "@googleapis/drive"
  - "google-auth-library"
---

## Installation

`@googleapis/drive` and `google-auth-library` are optional peer dependencies of `files-sdk` - install alongside the SDK so the adapter's imports resolve at runtime.

```package-install
files-sdk @googleapis/drive google-auth-library
```

## Usage

Google Drive via the official `@googleapis/drive` v3 client. Drive is a document manager rather than object storage - files have opaque `fileId`s and names can collide, so the adapter maps a unified string key onto Drive's `appProperties` (`fsdkKey`), with a per-instance LRU so reads after the first don't re-issue a lookup. Four auth modes: service-account credentials (inline or via key file), an OAuth refresh token, a pre-built Drive client (the escape hatch), or env-var fallback.

```ts lineNumbers
import { Files } from "files-sdk";
import { googleDrive } from "files-sdk/google-drive";

// Service account into a Shared Drive (recommended - the default
// service-account quota is 15 GB and not really intended for storage).
// Add the service account as a member of the Shared Drive in the
// Google Workspace admin console first.
const files = new Files({
  adapter: googleDrive({
    credentials: {
      client_email: process.env.GOOGLE_DRIVE_CLIENT_EMAIL!,
      private_key: process.env.GOOGLE_DRIVE_PRIVATE_KEY!,
    },
    driveId: process.env.GOOGLE_DRIVE_ID!,
    // Shared Drive root id, or a sub-folder id to scope the "bucket".
    rootFolderId: process.env.GOOGLE_DRIVE_ID!,
    // publicByDefault: true → grants anyone-with-link reader on upload
    //                       and url() returns the Drive download URL.
  }),
});
```

## Options

<AutoTypeTable
  path="../../packages/files-sdk/src/google-drive/index.ts"
  name="GoogleDriveAdapterOptions"
/>

## Limitations

Two files with the same virtual key (created out-of-band) make resolution throw `Conflict` rather than picking one silently. User `metadata` keys starting with `fsdk` are reserved - the adapter uses that prefix on Drive's `appProperties` for bookkeeping.

## Compatibility

| Method            | Status | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------- | :----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `upload`          |   ✅   |                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `download`        |   ✅   |                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `delete`          |   ✅   |                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `list`            |   ⚠️   | Drive has no native key field. The adapter scopes by parent folder and filters client-side to files carrying its `fsdkKey` appProperty - files written into the same folder out-of-band are excluded. `prefix` is filtered page-local and can under-return when the prefix isn't satisfied within a single page.                                                                                                                            |
| `search`          |   ⚠️   | Built on `listAll` — inherits this adapter's `list` behavior above. Client-side key match (glob, regex, substring, exact).                                                                                                                                                                                                                                                                                                                  |
| `head`            |   ✅   |                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `exists`          |   ⚠️   | Drive has no native key field. The adapter resolves by parent folder + `fsdkKey` appProperty, so files written into the same folder out-of-band return `false` even if a file with that name exists.                                                                                                                                                                                                                                        |
| `copy`            |   ✅   |                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `url`             |   ⚠️   | Throws by default - Drive has no signed URL primitive. With `publicByDefault: true` at construction, `upload()` grants `anyone, reader` and `url()` returns the permanent Drive download URL (`expiresIn` ignored). `responseContentDisposition` always throws - Drive's download URL has no Content-Disposition override.                                                                                                                  |
| `signedUploadUrl` |   ⚠️   | Initiates a Drive resumable session via `POST /upload/drive/v3/files?uploadType=resumable` and returns the session URL as a one-shot PUT. `maxSize` and `minSize` throw because Drive sessions do not enforce a server-side `content-length-range` policy; enforce size limits at your application gateway instead. Throws when the adapter was constructed via the pre-built `client` escape hatch (no auth handle to mint access tokens). |