{"id":1497,"library":"google-cloud-storage-control","title":"Google Cloud Storage Control","description":"The `google-cloud-storage-control` library provides a Python client for interacting with the Google Cloud Storage Control API. This API allows for programmatic management of Storage features like Managed Folders and other bucket-level controls. It is currently at version 1.11.0 and is part of the larger `google-cloud-python` monorepo, receiving frequent updates along with other Google Cloud client libraries.","status":"active","version":"1.11.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-storage-control","tags":["google cloud","storage","cloud storage","managed folders","gcs","gcp"],"install":[{"cmd":"pip install google-cloud-storage-control","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core functionalities for Google APIs, including gRPC/REST transport.","package":"google-api-core"},{"reason":"Handles authentication to Google Cloud services.","package":"google-auth"},{"reason":"Shared components for Google Cloud client libraries.","package":"google-cloud-core"},{"reason":"Provides Pythonic wrappers for Protocol Buffer messages.","package":"proto-plus"},{"reason":"Core Protocol Buffers library.","package":"protobuf"}],"imports":[{"symbol":"StorageControlClient","correct":"from google.cloud.storage_control_v2 import StorageControlClient"},{"note":"Always specify the API version (e.g., '_v2') for types if the client library supports multiple versions, even if only one is current. While `google.cloud.storage_control` might resolve in some cases, `_v2` is explicit and safer for future compatibility.","wrong":"from google.cloud.storage_control.types import ManagedFolder","symbol":"ManagedFolder","correct":"from google.cloud.storage_control_v2.types import ManagedFolder"}],"quickstart":{"code":"import os\nfrom google.cloud.storage_control_v2 import StorageControlClient\n\nproject_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')\nbucket_name = os.environ.get('GCS_BUCKET_NAME', 'your-gcs-bucket-name')\n\nif project_id == 'your-gcp-project-id':\n    print(\"Please set the GOOGLE_CLOUD_PROJECT environment variable or replace 'your-gcp-project-id'.\")\n    exit()\nif bucket_name == 'your-gcs-bucket-name':\n    print(\"Please set the GCS_BUCKET_NAME environment variable or replace 'your-gcs-bucket-name'.\")\n    exit()\n\nclient = StorageControlClient()\n\nparent_path = f\"projects/{project_id}/buckets/{bucket_name}\"\n\ntry:\n    # List managed folders in a bucket\n    print(f\"Listing managed folders in {parent_path}:\")\n    for managed_folder in client.list_managed_folders(parent=parent_path):\n        print(f\"- {managed_folder.name}\")\nexcept Exception as e:\n    print(f\"Error listing managed folders: {e}\")\n    print(\"Ensure you have appropriate IAM permissions (e.g., 'roles/storage.admin') for the bucket and that Application Default Credentials are configured.\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `StorageControlClient` and list managed folders within a specified Google Cloud Storage bucket. Ensure your `GOOGLE_CLOUD_PROJECT` and `GCS_BUCKET_NAME` environment variables are set, and your environment is authenticated (e.g., via `gcloud auth application-default login`)."},"warnings":[{"fix":"Upgrade to `google-cloud-storage-control>=1.0.0` and consult the official changelog for specific migration steps. Re-evaluate client instantiation and method calls to align with the `v2` API.","message":"The `google-cloud-storage-control` library transitioned from version `0.x.x` to `1.x.x` (released 2023-08-09). This major version bump primarily adopted the Storage Control API v2. Users migrating from `0.x.x` might encounter breaking changes in client initialization, method signatures, and resource representations.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure the service account or user making the request has the necessary Storage Control permissions, such as `roles/storage.admin` or custom roles with granular permissions for `managedFolders.create`, `managedFolders.get`, `managedFolders.list`, `managedFolders.delete`.","message":"Managed Folders are a new feature and require specific IAM permissions beyond standard bucket access. Incorrect or insufficient permissions can lead to `PermissionDenied` errors.","severity":"gotcha","affected_versions":"All"},{"fix":"Always construct resource paths using the exact `projects/{project_id}/buckets/{bucket_name}` pattern, or other specific resource patterns as documented for each method, to avoid `Invalid argument` errors.","message":"Resource paths for operations (e.g., `parent` for `list_managed_folders`) must follow a strict format like `projects/{project_id}/buckets/{bucket_name}`.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade your Python environment to version 3.10 or newer. After upgrading Python, ensure that `google-api-core`, `google-auth`, and `google-cloud-storage-control` are updated to their latest versions.","message":"Using Python 3.9 (or older versions past their end-of-life) with `google-cloud-storage-control` and its dependencies (like `google-api-core`, `google-auth`) will result in `FutureWarning` messages. Future updates and critical bug fixes may not be provided for these unsupported Python versions.","severity":"gotcha","affected_versions":"python_version:<3.10"},{"fix":"Ensure the `GOOGLE_CLOUD_PROJECT` environment variable is set or explicitly pass your project ID when initializing the client or making API calls that require it, for example: `ManagedFolderClient(project='your-gcp-project-id')`.","message":"The `google-cloud-storage-control` library typically requires a Google Cloud Project ID for its operations. This can be provided programmatically during client instantiation or implicitly by setting the `GOOGLE_CLOUD_PROJECT` environment variable.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'1.11.0':48 'allow':27 'along':63 'api':24,26 'bucket':40 'bucket-level':39 'client':15,68 'cloud':2,8,21,57,67,71,73 'control':4,10,23,42 'current':45 'featur':33 'folder':36,76 'frequent':61 'gcp':78 'gcs':77 'googl':1,7,20,56,66,70 'google-cloud-python':55 'google-cloud-storage-control':6 'interact':17 'larger':54 'level':41 'librari':11,69 'like':34 'manag':30,35,75 'monorepo':59 'part':51 'programmat':29 'provid':12 'python':14,58 'receiv':60 'storag':3,9,22,32,72,74 'updat':62 'version':47","created_at":"2026-04-09T03:50:28.967890+00:00","updated_at":"2026-04-16T15:24:12.596620+00:00","problems":[{"fix":"Ensure the library is correctly installed using pip: `pip install google-cloud-storage-control`","cause":"The `google-cloud-storage-control` library has not been installed in your Python environment, or there's an issue with your Python path or virtual environment.","error":"ModuleNotFoundError: No module named 'google.cloud.storage_control'"},{"fix":"The `StorageControlClient` should be imported from `google.cloud.storage_control_v2.services.storage_control.client` (or similar versioned path) or just `google.cloud.storage_control_v2` and then instantiated. The recommended way is to import the main client from the root of the installed library `google.cloud.storage_control_v2` and then access the client directly. For `google-cloud-storage-control` (which is `storage_control_v2` under the hood), the current recommended import is: `from google.cloud import storage_control_v2\nclient = storage_control_v2.StorageControlClient()`","cause":"This is a common wrong import pattern where developers try to import the client class directly from the top-level package, instead of from the `services` submodule, or instantiate it incorrectly.","error":"from google.cloud.storage_control import StorageControlClient\nclient = StorageControlClient()"},{"fix":"Grant the appropriate IAM roles to the principal. For Managed Folders, this typically includes roles like `Storage Managed Folder Creator`, `Storage Managed Folder Viewer`, `Storage Managed Folder Deleter`, or custom roles with permissions like `storage.managedFolders.create` or `storage.managedFolders.update` at the project or bucket level.","cause":"The authenticated principal (user or service account) does not have the necessary IAM permissions to perform the requested Managed Folder operation (e.g., create, get, list, delete) on the specified Google Cloud Storage bucket or Managed Folder.","error":"google.api_core.exceptions.PermissionDenied: 403 Forbidden: Missing or insufficient permissions to access this resource. Managed Folder operations require specific IAM roles."},{"fix":"Ensure the Managed Folder name ends with a forward slash (`/`) and complies with all other naming rules (e.g., valid Unicode characters, no control characters, no `.` or `..`, max 15 slashes for nesting depth). For example: `managed_folder_name = 'my-managed-folder/'`","cause":"The name provided for the Managed Folder does not adhere to Google Cloud Storage's naming conventions for Managed Folders, such as not ending with a forward slash (`/`).","error":"google.api_core.exceptions.BadRequest: 400 The managed folder name is invalid. Managed folder names must end with '/' and meet specific naming requirements."}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.14.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://cloud.google.com/storage","github":"https://github.com/googleapis/google-cloud-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/google-cloud-storage-control/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["gcp"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}