Install & Compatibility
Where this runs
tested against v1.16.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 2.045s · 68.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.4s · import 1.482s · 67MB
67MB installed
● package 67MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CloudFilestoreManagerClient
✓ from google.cloud.filestore_v1 import CloudFilestoreManagerClient
filestore_v1
✓ from google.cloud import filestore_v1
✗ from google.cloud.filestore import Client
The primary client class is `CloudFilestoreManagerClient` within the `filestore_v1` module, not a generic 'Client' directly under `google.cloud.filestore`.
This quickstart demonstrates how to initialize the `CloudFilestoreManagerClient` and list existing Filestore instances within a specified Google Cloud project and location. Ensure your `GOOGLE_CLOUD_PROJECT` environment variable is set or replace 'your-project-id' and 'us-central1' with your actual project ID and desired region. Authentication is handled automatically via Application Default Credentials (ADC).
import os
from google.cloud.filestore_v1 import CloudFilestoreManagerClient
project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-project-id') # Replace with your GCP project ID
location = 'us-central1' # Replace with a suitable region, e.g., 'us-central1'
def list_filestore_instances():
"""Lists all Filestore instances in a given project and location."""
client = CloudFilestoreManagerClient()
parent = f"projects/{project_id}/locations/{location}"
print(f"Listing Filestore instances in {parent}:")
try:
# The list_instances method returns a PagedAsyncIterator, which can be iterated directly
for instance in client.list_instances(parent=parent):
print(f" Instance: {instance.name.split('/')[-1]} (State: {instance.state.name}, Tier: {instance.tier.name})")
print(f" IP Address: {instance.networks[0].ip_addresses[0] if instance.networks else 'N/A'}")
print(f" Capacity: {instance.capacity_gb} GB")
except Exception as e:
print(f"Error listing instances: {e}")
if __name__ == '__main__':
list_filestore_instances()
Debug
Known issues
breakingPython 3.8 and older versions are no longer supported. Ensure your environment uses Python 3.9 or newer.fixUpgrade your Python environment to version 3.9 or later. The `google-cloud-filestore` library currently supports Python >= 3.9.
affects: <=1.x (older clients)
gotchaYou must enable the Filestore API for your Google Cloud project before creating or managing instances. This is a common oversight leading to API permission errors.fixEnable the Filestore API via the Google Cloud Console or using `gcloud services enable file.googleapis.com`.
affects: All versions
gotchaAuthentication is crucial. Ensure Application Default Credentials (ADC) are correctly set up, either by running `gcloud auth application-default login` for local development or by configuring service account credentials in production environments.fixFollow the Google Cloud authentication guide. For local development, `gcloud auth application-default login`. For production, ensure your service account has the necessary IAM roles (e.g., `roles/filestore.viewer` or `roles/filestore.editor`).
affects: All versions
gotchaFilestore instances are zonal or regional. Deploying your Filestore instance in a different zone or region than your Compute Engine VMs or GKE cluster can lead to increased latency and cross-zone networking costs.fixAlways place your Filestore instances in the same zone or region as the compute resources that will access them.
affects: All versions
gotchaThe client library logs RPC events using Python's standard logging, and these logs might contain sensitive information. By default, these logs are not handled, so you must configure log handling explicitly.fixConfigure Python's logging module to handle logs from `google.cloud.filestore_v1` if you need to capture them. Exercise caution when storing logs that may contain sensitive data.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'google.cloud.filestore'
The `google-cloud-filestore` client library is not installed in the Python environment, or there is a conflict with an older, deprecated `google-cloud` meta-package.
fixEnsure the specific `google-cloud-filestore` package is installed: `pip install google-cloud-filestore`. If issues persist, uninstall any deprecated `google-cloud` package: `pip uninstall google-cloud` before reinstalling.
PERMISSION_DENIED: Permission 'file.instances.create' denied on 'projects/----`
The authenticated Google Cloud account or service account lacks the necessary IAM permissions (e.g., `roles/file.editor` or `roles/file.serviceAgent`) to create Filestore instances, or the Filestore API is not enabled for the project.
fixEnable the Filestore API for your project (`gcloud services enable file.googleapis.com`) and ensure the account performing the operation has the `Cloud Filestore Editor` role or equivalent permissions. Check if the `file.serviceAgent` role has been removed from the Filestore service account.
mount.nfs: access denied by server while mounting
This error typically indicates that the client attempting to mount the Filestore instance does not have the correct network configuration, firewall rules are blocking access, or the NFS export options on the Filestore instance do not permit access from the client's IP address.
fixVerify that your VPC network and firewall rules (e.g., ports 111, 2049, 2050, 4001, 4045 for NFS) are correctly configured to allow traffic between the client and the Filestore instance. Check the Filestore instance's NFS export options to ensure the client's IP address range is permitted.
System limit for internal resources has been reached
This error occurs when Filestore has reached an internal network quota, often due to a large number of internal networks created over time, even if associated Filestore instances and VPC networks have been deleted.
fixDelete all existing Filestore instances and backups, then disable and re-enable the Filestore API for your project. If you cannot disable the API or need to retain quotas, contact Google Cloud Support to adjust network limits.
INVALID_ARGUMENT: network '[SHARED_VPC_NETWORK]' does not exist. (When creating Filestore instance from a service project in a Shared VPC setup)
When using Shared VPC, Filestore instances often cannot be created directly from a service project if the Shared VPC network is not properly recognized or configured for this operation, particularly if private service access is not enabled or proper IAM roles are missing.
fixCreate the Filestore instance from the *host project* of the Shared VPC, using the Shared VPC network as the authorized network. Ensure private service access is enabled for the Shared VPC network and that the necessary `Owner`, `Editor`, or `Network Management Admin` roles are assigned.
Upgrade
Version history
1.16.0latest on PyPI · released Mar 30, 2026
Audit
Dependencies
No dependency data recorded yet.