Registry / gcp / google-cloud-storage-control

google-cloud-storage-control

library1.14.0pypypi✓ verified 24d ago

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.

gcp

pip install google-cloud-storage-control

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GOOGLE-CLOUD-STORA

google-cloud-storage-control

gcppythonv1.14.0

Install

5.6s avg

Import

1559ms

Disk

69MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.14.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.95 runs

installs and imports cleanly · install 0.0s · import 1.864s · 70.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 5.6s · import 1.254s · 69MB

69MB installed

● package 69MB

Code

Verified usage

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

StorageControlClient

✓ from google.cloud.storage_control_v2 import StorageControlClient

ManagedFolder

✓ from google.cloud.storage_control_v2.types import ManagedFolder

✗ from google.cloud.storage_control.types import ManagedFolder

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.

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`).

import os from google.cloud.storage_control_v2 import StorageControlClient project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id') bucket_name = os.environ.get('GCS_BUCKET_NAME', 'your-gcs-bucket-name') if project_id == 'your-gcp-project-id': print("Please set the GOOGLE_CLOUD_PROJECT environment variable or replace 'your-gcp-project-id'.") exit() if bucket_name == 'your-gcs-bucket-name': print("Please set the GCS_BUCKET_NAME environment variable or replace 'your-gcs-bucket-name'.") exit() client = StorageControlClient() parent_path = f"projects/{project_id}/buckets/{bucket_name}" try: # List managed folders in a bucket print(f"Listing managed folders in {parent_path}:") for managed_folder in client.list_managed_folders(parent=parent_path): print(f"- {managed_folder.name}") except Exception as e: print(f"Error listing managed folders: {e}") print("Ensure you have appropriate IAM permissions (e.g., 'roles/storage.admin') for the bucket and that Application Default Credentials are configured.")

Debug

Known issues

breakingThe `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.

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.

affects: <1.0.0

gotchaManaged Folders are a new feature and require specific IAM permissions beyond standard bucket access. Incorrect or insufficient permissions can lead to `PermissionDenied` errors.

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`.

affects: All

gotchaResource paths for operations (e.g., `parent` for `list_managed_folders`) must follow a strict format like `projects/{project_id}/buckets/{bucket_name}`.

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.

affects: All

gotchaUsing 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.

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.

affects: python_version:<3.10

gotchaThe `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.

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')`.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'google.cloud.storage_control'

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.

fix

Ensure the library is correctly installed using pip: `pip install google-cloud-storage-control`

from google.cloud.storage_control import StorageControlClient client = StorageControlClient()

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.

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
client = storage_control_v2.StorageControlClient()`

google.api_core.exceptions.PermissionDenied: 403 Forbidden: Missing or insufficient permissions to access this resource. Managed Folder operations require specific IAM roles.

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.

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.

google.api_core.exceptions.BadRequest: 400 The managed folder name is invalid. Managed folder names must end with '/' and meet specific naming requirements.

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 (`/`).

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/'`

Upgrade

Version history

1.14.0latest on PyPI · released Aug 24, 2026

Audit

Dependencies

google-api-corerequiredCore functionalities for Google APIs, including gRPC/REST transport.

google-authrequiredHandles authentication to Google Cloud services.

google-cloud-corerequiredShared components for Google Cloud client libraries.

proto-plusrequiredProvides Pythonic wrappers for Protocol Buffer messages.

protobufrequiredCore Protocol Buffers library.

Agent activity

26 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/googleapis/google-cloud-python ↗

packagehttps://pypi.org/project/google-cloud-storage-control/ ↗

homepagehttps://cloud.google.com/storage ↗