gcsfs

library2026.3.0pypypi✓ verified 52d ago

GCSFS provides a Pythonic file-system interface to Google Cloud Storage, allowing seamless interaction with GCS as if it were a local file system. The current version is 2026.3.0, and it follows a regular release cadence with updates approximately every few months.

gcp data

pip install gcsfs

github ↗package ↗docs ↗

Install & Compatibility

Where this runs

tested against v2026.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 2.702s · 86.3MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 8.6s · import 1.932s · 86MB

83MB installed

● package 83MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GCSFileSystem

✓ from gcsfs import GCSFileSystem

Ensure to import GCSFileSystem from gcsfs to interact with Google Cloud Storage.

This script demonstrates how to initialize a GCSFileSystem instance, list files in a GCS bucket, and read a file from GCS.

import gcsfs # Initialize the GCSFileSystem fs = gcsfs.GCSFileSystem(project='your-project-id') # List files in a bucket print(fs.ls('your-bucket-name')) # Read a file with fs.open('your-bucket-name/your-file.txt', 'rb') as f: print(f.read())

gcsfs --version

Debug

Known issues

breakingDefault Filesystem Implementation Change: gcsfs now uses ExtendedFileSystem as the default entry point for all bucket types to support specialized storage buckets like Hierarchical Namespace (HNS) out-of-box. This change may affect existing workflows that rely on the previous default implementation.

fix

If you experience unexpected behavior due to this change, you can revert to the previous implementation by setting the environment variable GCSFS_EXPERIMENTAL_ZB_HNS_SUPPORT=false before importing gcsfs.

affects: 2026.2.0 and later

gotchaFUSE functionality is experimental and may change. It is not recommended for production use, and data loss could occur if not used cautiously.

fix

Use FUSE functionality with caution and ensure data is backed up before performing operations.

affects: All versions with FUSE support

breakingAttempting to access a Google Cloud Storage bucket without proper authentication or sufficient IAM permissions results in a 401 Unauthorized error and 'Permission denied' message for operations like listing objects. This happens when the caller (e.g., your application) is anonymous or lacks the required IAM roles (e.g., `storage.objectViewer` or `storage.legacyBucketReader`) to perform the requested action on the specified bucket.

fix

Ensure your environment is correctly authenticated to Google Cloud (e.g., via `gcloud auth application-default login`, service account keys, or running on a GCE instance with appropriate scopes). Verify that the authenticated identity has the necessary IAM permissions (e.g., `storage.objects.list`) for the target Google Cloud Storage bucket. For anonymously accessible public buckets, ensure the bucket's IAM policy or ACLs explicitly allow public access for the operation.

affects: All versions

breakinggcsfs operation failed due to missing or invalid Google Cloud credentials. The application attempted to access a Google Cloud Storage bucket as an anonymous caller and lacked the necessary permissions (e.g., storage.objects.list), resulting in a 401 Unauthorized error. This typically means Application Default Credentials (ADC) were not found or were incorrectly configured.

fix

Ensure that Google Cloud Application Default Credentials (ADC) are properly configured in the execution environment. This can involve setting the GOOGLE_APPLICATION_CREDENTIALS environment variable to point to a service account key file, authenticating via `gcloud auth application-default login`, or ensuring that the compute environment (e.g., GCE, GKE, Cloud Run) has an attached service account with appropriate Storage Object Viewer/Admin roles.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'gcsfs'

The gcsfs library is not installed in your Python environment.

fix

Install the library using pip: `pip install gcsfs` or with conda: `conda install -c conda-forge gcsfs`.

Anonymous caller does not have storage.objects.list access to the Google Cloud Storage bucket

The Python environment or the executing service account lacks the necessary Google Cloud Storage permissions to list or access objects in the specified bucket.

fix

Ensure that your Google Cloud authentication is correctly set up (e.g., via `gcloud auth application-default login`, `GOOGLE_APPLICATION_CREDENTIALS` environment variable, or by passing `token` to `gcsfs.GCSFileSystem`). Verify that the authenticated identity has the 'Storage Object Viewer' or 'Storage Admin' IAM role for the GCS bucket.

OSError: Project was not passed and could not be determined from the environment

The Google Cloud project ID was not explicitly provided to gcsfs.GCSFileSystem and could not be automatically inferred from environment variables or gcloud configuration.

fix

Initialize `gcsfs.GCSFileSystem` with the `project` argument (e.g., `gcsfs.GCSFileSystem(project='your-project-id')`), or ensure the `GOOGLE_CLOUD_PROJECT` environment variable is set, or configure a default project using `gcloud config set project YOUR_PROJECT_ID`.

FileNotFoundError: gs://your-bucket/path/to/file

The specified file or bucket path does not exist in Google Cloud Storage, or the authenticated identity does not have permission to view it, making it appear as nonexistent.

fix

Double-check the bucket name and object path for any typos. Verify that the authenticated user or service account has `storage.objects.get` and `storage.objects.list` permissions for the target bucket and its contents.

Upgrade

Version history

2026.5.0latest on PyPI

Audit

Dependencies

fsspecrequiredGCSFS depends on fsspec for its file-system interface functionalities.

Agent activity

69 hits · last 30 days

node

seranking-bot

ahrefsbot