{"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,"last_verified":"2026-05-12T13:46:56.790Z","next_check":"2026-06-26T00:00:00.000Z","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,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.62,"mem_mb":38.8,"disk_size":"85.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.44,"mem_mb":32.5,"disk_size":"85M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.39,"mem_mb":41.8,"disk_size":"91.5M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.26,"mem_mb":36.1,"disk_size":"91M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.29,"mem_mb":41.2,"disk_size":"82.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.52,"mem_mb":35.6,"disk_size":"82M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.49,"mem_mb":42.7,"disk_size":"82.1M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.55,"mem_mb":37.4,"disk_size":"82M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.25,"mem_mb":22.5,"disk_size":"63.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.18,"mem_mb":22.5,"disk_size":"66M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}