gcsfs

|Build Status| |Docs|

GCSFS is a Python library that provides a familiar, file-system-like interface to Google Cloud Storage (GCS). Built on top of fsspec, it allows you to interact with cloud buckets as if they were local directories, making it a favorite for data scientists and engineers.

Getting Started

Installation

Install via pip or conda:

# Using pip
pip install gcsfs

# OR using conda
conda install -c conda-forge gcsfs

Basic Usage

import gcsfs

# Initialize the filesystem
fs = gcsfs.GCSFileSystem(project='my-google-project')

# List files in a bucket
files = fs.ls('my-bucket')

# Read a file directly into a string/bytes
with fs.open('my-bucket/data.txt', 'rb') as f:
    content = f.read()

Specialized Bucket Support

GCSFS now automatically supports advanced Google Cloud Storage features through its ExtendedFileSystem implementation.

1. Hierarchical Namespace (HNS)

Hierarchical Namespace (HNS) replaces the traditional "flat" GCS structure with true logical directories.

Atomic Renames: Moving or renaming a directory is an O(1) metadata operation. No more slow "copy-then-delete" for large folders.
High Performance: Offers up to 8x higher initial Queries Per Second (QPS) for read/write operations.
AI/ML Ready: Ideal for heavy checkpointing and managing millions of small files.

2. Rapid Buckets (Zonal Storage)

Rapid Buckets are zonal storage resources designed for ultra-low latency and maximum throughput.

Zonal Co-location: Place your data in the same zone as your GPU/TPU clusters to minimize network lag.
True Appends: Unlike standard GCS objects, you can append data to existing objects in Rapid buckets without a full rewrite.
Streaming I/O: Optimized for high-speed model loading and real-time logging.

Integration & Auth

GCSFS plays nicely with the rest of the Python data ecosystem.

Authentication Modes

Default: Uses your local gcloud credentials or environment service accounts.
Cloud: Explicitly use Google Metadata service (token='cloud').
Anonymous: Access public data without a login (token='anon').
Service Account: Pass the path to your JSON key file (token='path/to/key.json').

[!TIP] Note on Async: GCSFS is built on aiohttp. If you are building high-concurrency applications, you can use the asynchronous API by passing asynchronous=True to the GCSFileSystem constructor.

Support

Work on this repository is supported in part by:

"Anaconda, Inc. - Advancing AI through open source."

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gcsfs-2026.8.0.tar.gz (1.1 MB view details)

Uploaded Aug 13, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

gcsfs-2026.8.0-py3-none-any.whl (91.4 kB view details)

Uploaded Aug 13, 2026 Python 3

File details

Details for the file gcsfs-2026.8.0.tar.gz.

File metadata

Download URL: gcsfs-2026.8.0.tar.gz
Upload date: Aug 13, 2026
Size: 1.1 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gcsfs-2026.8.0.tar.gz
Algorithm	Hash digest
SHA256	`c2a7c0ffee2d0837243b4f838efaa185c152a4eb4cc529e41b3569bf00b9781e`
MD5	`157bfa181251d86f5b93bf191f66b1f9`
BLAKE2b-256	`683a194b5e67b78586a45fb36958800a30783c24c07b7f1c0e82d347f01346c6`

See more details on using hashes here.

Provenance

The following attestation bundles were made for gcsfs-2026.8.0.tar.gz:

Publisher: release-on-merge.yml on fsspec/gcsfs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: gcsfs-2026.8.0.tar.gz
- Subject digest: c2a7c0ffee2d0837243b4f838efaa185c152a4eb4cc529e41b3569bf00b9781e
- Sigstore transparency entry: 2450592514
- Sigstore integration time: Aug 13, 2026
Source repository:
- Permalink: fsspec/gcsfs@ea2a1fff67ee8eb2fa43d55b25b24819d4e636cf
- Branch / Tag: refs/heads/main
- Owner: https://github.com/fsspec
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-on-merge.yml@ea2a1fff67ee8eb2fa43d55b25b24819d4e636cf
- Trigger Event: pull_request