Install & Compatibility
Where this runs
tested against v0.5.35 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.756s · 24.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.3s · import 0.676s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
encoding
✓ from apitools.base.py import encoding
Used for message serialization and deserialization (e.g., `DictToMessage`, `MessageToDict`).
HttpError
✓ from apitools.base.py import exceptions
✗ from apitools.base.py.exceptions import HttpError
While `HttpError` is defined in `apitools.base.py.exceptions`, the common and recommended import pattern is to import the `exceptions` module itself.
GetCredentials
✓ from apitools.base.py import credentials_lib
A helper function to retrieve Google application credentials.
Http
✓ from apitools.base.py import http_wrapper
To obtain the underlying `httplib2.Http` object, typically through methods like `http_wrapper.MakeRequest.http()` or other helpers within the `http_wrapper` module.
This quickstart demonstrates core apitools functionalities: converting Python dictionaries to message objects (simulating usage with a generated client's message class) and back, and catching a simulated `HttpError`. It highlights the library's role in serialization/deserialization and error handling, which are central to its use with auto-generated API clients.
from apitools.base.py import encoding
from apitools.base.py import exceptions
# Apitools is primarily used with auto-generated client libraries
# that define specific Message classes. For demonstration, we'll
# define a simple Message using apitools' base Message class.
class MySimpleMessage(encoding.Message):
field1 = encoding.StringField(1)
field2 = encoding.IntegerField(2)
# 1. Convert a Python dictionary to an apitools Message
data_dict = {'field1': 'Hello Apitools', 'field2': 42}
message_instance = encoding.DictToMessage(data_dict, MySimpleMessage)
print(f"Original dict: {data_dict}")
print(f"Converted Message: {message_instance}")
print(f"Accessing message fields: {message_instance.field1}, {message_instance.field2}")
# 2. Convert an apitools Message back to a Python dictionary
dict_from_message = encoding.MessageToDict(message_instance)
print(f"Converted back to dict: {dict_from_message}")
# 3. Handle simulated HttpError (common in API interactions)
try:
# In a real scenario, this error would be raised during an API call
raise exceptions.HttpError(
'https://api.example.com/data/404',
request_headers={'User-Agent': 'apitools-demo'},
response_headers={'Content-Type': 'application/json'},
status_code=404,
content=b'{"error": "Resource not found"}'
)
except exceptions.HttpError as e:
print(f"\nCaught a simulated HTTP Error:")
print(f"Status Code: {e.status_code}")
print(f"Error Content: {e.content.decode('utf-8')}")
print(f"URL: {e.url}")
Debug
Known issues
breakingThis library is officially deprecated and not actively developed. It is maintained only for use by the Google Cloud SDK. New projects should NOT use `google-apitools` directly; instead, use the official Google Cloud Client Libraries for specific services (e.g., `google-cloud-storage`, `google-cloud-bigquery`).fixFor new projects, migrate to modern Google Cloud Client Libraries (e.g., `google-cloud-*`). For existing projects that depend on it via Cloud SDK, continue usage but be aware of its deprecated status.
affects: All versions, especially current (0.5.35) and future.
breakingVersion 0.5.5 was an emergency release due to a backwards incompatible change in `oauth2client` 4.0.0. This indicates tight coupling with older dependency versions, which might break with newer versions of its core dependencies if not carefully managed.fixIf `apitools <0.5.5` is used, ensure `oauth2client` is pinned to a compatible version (e.g., `<4.0.0`). If using `oauth2client >=4.0.0`, `apitools` should be `0.5.5+`. However, given the deprecation, upgrading `apitools` for new projects is not recommended.
affects: <0.5.5
gotchaThe library heavily supports Python 2.7 (indicated by `requires_python: >=2.7`). While it works with Python 3, its design and maintenance context are rooted in an older era of Python development, which might lead to unexpected behaviors or compatibility issues in modern Python 3-only environments.fixAvoid using in new Python 3-only projects. For existing projects, ensure thorough testing for Python 3 compatibility, especially with newer Python 3.x releases (e.g., 3.9+).
affects: All versions, especially when used in modern Python 3.x projects.
gotchaApitools is primarily designed for use with *auto-generated* client libraries specific to Google APIs. Direct usage of its base components (like `Http` or `encoding`) for general REST API interaction can be more complex and less intuitive compared to other, more actively maintained HTTP client libraries (e.g., `requests`).fixIf not using a generated Apitools client, consider using a more general-purpose and actively maintained HTTP client library like `requests`.
affects: All versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'google-apitools'
This error occurs when the 'google-apitools' library is not installed in your Python environment or is not accessible within the environment where your code is running.
fixInstall the library using pip: `pip install google-apitools`.
apitools.base.py.exceptions.HttpForbiddenError: HttpError accessing
This error typically indicates an authentication or authorization issue, meaning your application lacks the necessary permissions (incorrect credentials, insufficient scopes, or access denied to the resource) to perform the requested operation.
fixEnsure your Google Cloud project credentials are correctly configured and have the appropriate OAuth 2.0 scopes enabled for the API you are trying to access. Verify the service account or user account has the necessary IAM roles and permissions. For local development, use `gcloud auth application-default login` or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
AttributeError: module 'google.api_core' has no attribute 'gapic_v1'
This `AttributeError` often arises from version conflicts between `google-apitools` and other Google client libraries, specifically `google-api-core` or `google-api-python-client`, where an older or incompatible version of one library is being used with a newer or incompatible version of another.
fixPin `google-api-core` to a compatible older version (e.g., `google-api-core==1.16.0`) or ensure all Google client libraries are updated to versions that are known to be compatible with each other and with the deprecated `google-apitools` if you must still use it. This often involves updating `google-api-python-client` as well. For new projects, migrate to the officially supported Google Cloud Client Libraries.
AttributeError: module 'googleapiclient' has no attribute '__version__'
This error is caused by an incompatibility between the installed version of `google-api-python-client` and its dependencies or by improper import statements. It often occurs when the `googleapiclient` package is not correctly updated or its internal structure is unexpectedly referenced.
fixUpgrade `google-api-python-client` to its latest version: `pip install --upgrade google-api-python-client`. If the issue persists, verify that `setuptools` is also up-to-date and consider rebuilding your virtual environment.
Upgrade
Version history
0.5.35latest on PyPI · released Sep 24, 2025
Audit
Dependencies
httplib2requiredProvides underlying HTTP client functionality.
oauth2clientrequiredHandles authentication and authorization via OAuth2.
protorpcrequiredFramework for defining and serializing structured messages and RPC services.
sixrequiredUtilities for Python 2 and 3 compatibility.