{"id":433,"library":"gcsfs","title":"GCSFS","description":"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.","status":"active","version":"2026.3.0","language":"python","source_language":"en","source_url":"https://github.com/fsspec/gcsfs","tags":["Google Cloud Storage","Python","File System Interface","Cloud Storage"],"install":[{"cmd":"pip install gcsfs","lang":"bash","label":"Install via pip"},{"cmd":"conda install -c conda-forge gcsfs","lang":"bash","label":"Install via conda"}],"dependencies":[{"reason":"GCSFS depends on fsspec for its file-system interface functionalities.","package":"fsspec","optional":false}],"imports":[{"note":"Ensure to import GCSFileSystem from gcsfs to interact with Google Cloud Storage.","symbol":"GCSFileSystem","correct":"from gcsfs import GCSFileSystem"}],"quickstart":{"code":"import gcsfs\n\n# Initialize the GCSFileSystem\nfs = gcsfs.GCSFileSystem(project='your-project-id')\n\n# List files in a bucket\nprint(fs.ls('your-bucket-name'))\n\n# Read a file\nwith fs.open('your-bucket-name/your-file.txt', 'rb') as f:\n    print(f.read())","lang":"python","description":"This script demonstrates how to initialize a GCSFileSystem instance, list files in a GCS bucket, and read a file from GCS."},"warnings":[{"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.","message":"Default 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.","severity":"breaking","affected_versions":"2026.2.0 and later"},{"fix":"Use FUSE functionality with caution and ensure data is backed up before performing operations.","message":"FUSE functionality is experimental and may change. It is not recommended for production use, and data loss could occur if not used cautiously.","severity":"gotcha","affected_versions":"All versions with FUSE support"},{"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.","message":"Attempting 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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"gcsfs 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.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'2026.3.0':31 'allow':14 'approxim':41 'cadenc':38 'cloud':12,46,52 'current':28 'everi':42 'file':7,25,49 'file-system':6 'follow':34 'gcs':18 'gcsfs':1,2 'googl':11,45 'interact':16 'interfac':9,51 'local':24 'month':44 'provid':3 'python':5,48 'regular':36 'releas':37 'seamless':15 'storag':13,47,53 'system':8,26,50 'updat':40 'version':29","created_at":"2026-03-28T12:02:22.862855+00:00","updated_at":"2026-04-16T15:13:54.313910+00:00","problems":[{"fix":"Install the library using pip: `pip install gcsfs` or with conda: `conda install -c conda-forge gcsfs`.","cause":"The gcsfs library is not installed in your Python environment.","error":"ModuleNotFoundError: No module named 'gcsfs'"},{"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.","cause":"The Python environment or the executing service account lacks the necessary Google Cloud Storage permissions to list or access objects in the specified bucket.","error":"Anonymous caller does not have storage.objects.list access to the Google Cloud Storage bucket"},{"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`.","cause":"The Google Cloud project ID was not explicitly provided to gcsfs.GCSFileSystem and could not be automatically inferred from environment variables or gcloud configuration.","error":"OSError: Project was not passed and could not be determined from the environment"},{"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.","cause":"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.","error":"FileNotFoundError: gs://your-bucket/path/to/file"}],"ecosystem":"pypi","meta_description":null,"install_score":95,"quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"2026.5.0","cli_name":"gcsfs","cli_version":"sh: 1: gcsfs: not found","type":"library","homepage":null,"github":"https://github.com/fsspec/gcsfs","docs":"https://gcsfs.readthedocs.io","changelog":null,"pypi":"https://pypi.org/project/gcsfs/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["gcp","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}