Install & Compatibility
Where this runs
tested against v3.15.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.95 runs
installs and imports cleanly · install 0.0s · import 1.844s · 74.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.2s · import 1.248s · 73MB
73MB installed
● package 73MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ImageAnnotatorClient
✓ from google.cloud.vision import ImageAnnotatorClient
✗ from google.cloud import vision
This quickstart demonstrates how to perform label detection on an image from a Google Cloud Storage (GCS) URI. Ensure you have set up Application Default Credentials, typically by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file, or by running `gcloud auth application-default login` for local development. For production environments on Google Cloud, authentication is usually handled automatically by the attached service account.
import os
from google.cloud import vision
# Set up authentication if running locally (e.g., via service account key file)
# On Google Cloud (e.g., GCE, Cloud Functions), this is often handled automatically.
# os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = os.environ.get('GOOGLE_APPLICATION_CREDENTIALS', '/path/to/your/keyfile.json')
def detect_labels_uri(image_uri):
"""Detects labels in the image located in Google Cloud Storage or on the Web."""
client = vision.ImageAnnotatorClient()
image = vision.Image()
image.source.image_uri = image_uri
response = client.label_detection(image=image)
labels = response.label_annotations
print('Labels:')
for label in labels:
print(f'{label.description}: {label.score:.2f}')
# Example usage with a publicly accessible image URI
# Make sure the image URI is publicly accessible or your service account has GCS read permissions.
detect_labels_uri('gs://cloud-samples-data/vision/label/wakeupcat.jpg')
Debug
Known issues
gotchaAuthentication is critical and often a source of error. Ensure your environment has valid credentials, typically via the `GOOGLE_APPLICATION_CREDENTIALS` environment variable pointing to a service account key file. On Google Cloud infrastructure (e.g., Compute Engine, Cloud Functions), credentials are often automatically inferred from the service account attached to the resource. Make sure the service account has the 'Cloud Vision API User' role and any necessary GCS permissions if accessing images from buckets.fixSet `GOOGLE_APPLICATION_CREDENTIALS` environment variable. Grant the 'Cloud Vision API User' IAM role to your service account. For GCS images, ensure the service account also has 'Storage Object Viewer' or similar access.
affects: All versions
breakingOlder versions of the client library used `vision.Client()` for instantiation and directly accessed types like `vision.types.Image`. The recommended and current approach uses `vision.ImageAnnotatorClient()` and accesses types directly from the `vision` module (e.g., `vision.Image`, `vision.Feature`).fixUpdate your code to use `client = vision.ImageAnnotatorClient()` and refer to types as `vision.Image`, `vision.Feature`, etc. Refer to the migration guide for older versions (though the PyPI version is 3.x, older client libraries could have been 0.x).
affects: <= 0.25.0
gotchaThe Google Cloud Vision API requires a Google Cloud project with billing enabled and the Vision API explicitly enabled. Even free tier usage counts against an enabled billing account.fixVisit the Google Cloud Console, select your project, ensure billing is enabled, and navigate to 'APIs & Services > Library' to enable the 'Cloud Vision API'.
affects: All versions
gotchaExceeding API quotas or sending malformed image data are common causes of failures. Errors like `RESOURCE_EXHAUSTED` (429) indicate quota limits, while `INVALID_ARGUMENT` (400) often points to issues with the image format, size, or content.fixMonitor your API usage in the Google Cloud Console. Validate image inputs (format, size) before sending them. Implement retry logic with exponential backoff for transient errors like `RESOURCE_EXHAUSTED`.
affects: All versions
deprecatedSpecific features within the Vision API have deprecation timelines. 'Vision API Celebrity Recognition' and 'OCR On-Prem' features are deprecated and scheduled for shutdown by September 16, 2025.fixReview the official Vision API deprecations page for details. For OCR On-Prem, migrate to the standard Vision API OCR. Evaluate alternatives or plan for shutdown for other deprecated features.
affects: All versions using these specific features
gotchaAutoML Vision, a distinct product for custom image models, has had its legacy version deprecated and moved to Vertex AI. This is sometimes confused with the core Cloud Vision API, which remains actively developed and supported.fixUnderstand the distinction between the pre-trained Cloud Vision API and AutoML Vision. If you are using AutoML Vision, migrate to Vertex AI as recommended.
affects: Users of AutoML Vision (not the core Vision API)
Upgrade
Version history
3.15.0latest on PyPI · released Jun 22, 2026
Audit
Dependencies
PythonrequiredRequired for the client library.