gdrive-fsspec

fsspec docs · contributing

---

gdrive-fsspec implements the fsspec interface for Google Drive. List directories, read and write files, and plug into any library that speaks fsspec.

Quickstart

# Currently, you need to install from the GitHub repository, there is no PyPI package yet.
pip install git+https://github.com/marimo-team/gdrive-fsspec

from gdrive_fsspec import GoogleDriveFileSystem

# First run: token="browser". Later: token="cache"
fs = GoogleDriveFileSystem(token="cache")

for entry in fs.ls(""):
    print(entry["name"], entry["type"])

with fs.open("my-folder/data.csv", "rb") as f:
    print(f.read())

Most filesystem operations follow the fsspec usage guide.

Why use gdrive-fsspec

1. fsspec-native — same API as S3, GCS, and local filesystems; works with ecosystem tools that accept an AbstractFileSystem.
2. Flexible auth — user OAuth, service accounts, or anonymous read-only access to public files.
3. Shared Drives — target a Shared Drive by name via the drive= argument (required for service-account uploads).
4. Scoped access — read_only or full_control OAuth scopes.

Authentication

User OAuth (personal Drive)

A browser opens on first use; the token is cached for later sessions.

fs = GoogleDriveFileSystem(token="browser")  # first time
fs = GoogleDriveFileSystem(token="cache")    # reuse cached token

On headless or remote machines (SSH, containers, CI), pass use_local_webserver=False in auth_kwargs to authenticate via the console:

fs = GoogleDriveFileSystem(
    token="browser",
    auth_kwargs={"use_local_webserver": False},
)

Service account

Provide a dict with the service account credentials from the GCP console (same content as the downloaded JSON). See Google's service account key docs.

fs = GoogleDriveFileSystem(
    creds=service_account_credentials,
    token="service_account",
    drive="My Shared Drive",  # required for uploads
)

Service accounts have no personal storage quota. Uploads must target a Shared Drive where the account is at least a Contributor. See Google's storage-limit errors.

Anonymous (public files)

For files shared publicly ("anyone with the link"), no authentication is needed:

fs = GoogleDriveFileSystem(token="anon")

See the GoogleDriveFileSystem docstring for root_file_id, access, spaces, and other options.

Google-native files (Docs, Sheets, Slides)

Google Workspace files have no binary content and cannot be downloaded directly; they must be exported to another format. gdrive-fsspec does this transparently: opening one for reading exports it to a sensible default format (Docs → text/plain, Sheets → xlsx, Slides/Drawings → PDF).

# Reads the doc's text via an automatic export.
with fs.open("notes/meeting.gdoc", "rb") as f:
    print(f.read().decode())

# Choose a specific export format.
with fs.open("notes/meeting.gdoc", "rb", export_mime_type="application/pdf") as f:
    pdf_bytes = f.read()

# Or export explicitly. Omit mime_type to use the default for the file type.
xlsx_bytes = fs.export("data/sheet.gsheet")

# Pass a mime_type to override the default.
csv_bytes = fs.export("data/sheet.gsheet", "text/csv")

The valid targets for each file type are available via fs.export_formats. Note that exporting a multi-sheet spreadsheet to text/csv only yields the first sheet, which is why xlsx is the default.

Installation

pip install git+https://github.com/marimo-team/gdrive-fsspec

Contributing

Contributions welcome — see CONTRIBUTING.md for setup, tests, and CI.

Related projects

• PyDrive2 — another fsspec-compatible Google Drive implementation