{"id":504,"library":"google-cloud-vision","title":"Google Cloud Vision","description":"The `google-cloud-vision` Python client library provides access to the Google Cloud Vision API, a powerful service for image analysis. It enables developers to integrate vision detection features like image labeling, optical character recognition (OCR), face and landmark detection, object localization, and explicit content tagging into their applications. This library is actively maintained by Google, with frequent updates released as part of the broader `google-cloud-python` monorepo.","status":"active","version":"3.13.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-vision","tags":["google cloud","vision","ai","image analysis","ocr","machine learning","computer vision"],"install":[{"cmd":"pip install google-cloud-vision","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for the client library.","package":"Python","optional":false}],"imports":[{"note":"The `Client` class was deprecated and replaced by `ImageAnnotatorClient` in older client library versions (e.g., v0.25.1 migration). Always use `ImageAnnotatorClient`.","wrong":"from google.cloud.vision import Client","symbol":"ImageAnnotatorClient","correct":"from google.cloud import vision\nclient = vision.ImageAnnotatorClient()"},{"note":"Image-related types are now directly accessible through the `vision` module.","symbol":"Image","correct":"from google.cloud import vision\nimage = vision.Image(content=b'...')"},{"note":"Feature-related types are now directly accessible through the `vision` module.","symbol":"Feature","correct":"from google.cloud import vision\nfeature = vision.Feature(type_=vision.Feature.Type.LABEL_DETECTION)"}],"quickstart":{"code":"import os\nfrom google.cloud import vision\n\n# Set up authentication if running locally (e.g., via service account key file)\n# On Google Cloud (e.g., GCE, Cloud Functions), this is often handled automatically.\n# os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = os.environ.get('GOOGLE_APPLICATION_CREDENTIALS', '/path/to/your/keyfile.json')\n\ndef detect_labels_uri(image_uri):\n    \"\"\"Detects labels in the image located in Google Cloud Storage or on the Web.\"\"\"\n    client = vision.ImageAnnotatorClient()\n    image = vision.Image()\n    image.source.image_uri = image_uri\n\n    response = client.label_detection(image=image)\n    labels = response.label_annotations\n    print('Labels:')\n\n    for label in labels:\n        print(f'{label.description}: {label.score:.2f}')\n\n# Example usage with a publicly accessible image URI\n# Make sure the image URI is publicly accessible or your service account has GCS read permissions.\ndetect_labels_uri('gs://cloud-samples-data/vision/label/wakeupcat.jpg')\n","lang":"python","description":"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."},"warnings":[{"fix":"Set `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.","message":"Authentication 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update 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).","message":"Older 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`).","severity":"breaking","affected_versions":"<= 0.25.0"},{"fix":"Visit the Google Cloud Console, select your project, ensure billing is enabled, and navigate to 'APIs & Services > Library' to enable the 'Cloud Vision API'.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor 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`.","message":"Exceeding 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review 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.","message":"Specific 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.","severity":"deprecated","affected_versions":"All versions using these specific features"},{"fix":"Understand the distinction between the pre-trained Cloud Vision API and AutoML Vision. If you are using AutoML Vision, migrate to Vertex AI as recommended.","message":"AutoML 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.","severity":"gotcha","affected_versions":"Users of AutoML Vision (not the core Vision API)"}],"env_vars":null,"last_verified":"2026-05-12T14:27:33.127Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Ensure the library is correctly installed using pip: `pip install google-cloud-vision` or `python3 -m pip install google-cloud-vision`. If using a virtual environment, ensure it is activated before installation and execution.","cause":"This error occurs when the `google-cloud-vision` library is not installed in the Python environment being used, or the Python interpreter cannot find the installed package.","error":"ModuleNotFoundError: No module named 'google.cloud.vision'"},{"fix":"Verify that the Google Cloud Vision API is enabled for your project. Ensure the service account or user has the 'Vision API User' role (`roles/vision.user`) and, if accessing images from Cloud Storage, the 'Storage Object Viewer' role (`roles/storage.objectViewer`) on the relevant bucket. Also, confirm that the `GOOGLE_APPLICATION_CREDENTIALS` environment variable correctly points to a valid service account key file.","cause":"This typically indicates that the authenticated service account or user lacks the necessary IAM permissions to access the Google Cloud Vision API, the specific project, or the Google Cloud Storage bucket containing the image.","error":"google.api_core.exceptions.PermissionDenied: 403 The caller does not have permission"},{"fix":"Check the image data for corruption, ensure it's a supported format (JPEG, PNG, GIF, BMP, WEBP, RAW, ICO, PDF, TIFF), and verify that base64 encoded strings are valid. If using a GCS URI, confirm it follows the `gs://bucket_name/object_name` format and that the object exists and is accessible.","cause":"This error signifies that the request sent to the Vision API is malformed, contains incorrect data, or specifies an unsupported image format or URI.","error":"google.api_core.exceptions.InvalidArgument: 400 Request contains an invalid argument."},{"fix":"Instead of `vision.Image()`, use `vision.types.Image()` or `vision_v1.types.Image()` if you've imported a specific version, or directly instantiate with content: `image = vision.Image(content=content)`.","cause":"This error indicates that the `Image` class is not directly accessible under the `google.cloud.vision` module in the current version of the library. The client library structure changed how image objects are instantiated.","error":"AttributeError: module 'google.cloud.vision' has no attribute 'Image'"},{"fix":"Use the `text_detection` feature within an `annotate_image` call. For example: `response = client.text_detection(image=image)` (if using the older simplified client) or more commonly: `response = client.annotate_image({'image': image, 'features': [{'type': vision.Feature.Type.TEXT_DETECTION}]})`.","cause":"This error occurs when attempting to call `text_detection` directly on an `ImageAnnotatorClient` instance. The correct method for text detection is `text_detection()` as part of a `client.annotate_image()` or `client.batch_annotate_images()` request, or the simplified `label_detection`, `face_detection`, etc. methods which take an `Image` object. The `text_detection` method is not a direct attribute of the client object itself.","error":"AttributeError: 'ImageAnnotatorClient' object has no attribute 'text_detection'"}],"ecosystem":"pypi","meta_description":null,"install_score":95,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.94,"mem_mb":26.8,"disk_size":"72.6M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.08,"mem_mb":22,"disk_size":"70M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.69,"mem_mb":28.7,"disk_size":"78.0M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.68,"mem_mb":24.3,"disk_size":"76M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.71,"mem_mb":28.5,"disk_size":"69.3M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.12,"mem_mb":23.5,"disk_size":"67M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.63,"mem_mb":28.9,"disk_size":"68.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.55,"mem_mb":24.4,"disk_size":"67M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.8,"mem_mb":26.6,"disk_size":"72.8M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.28,"mem_mb":21.8,"disk_size":"71M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}