Registry / gcp / google-cloud-documentai

google-cloud-documentai

library3.15.0pypypi✓ verified 22d ago

Google Cloud Document AI (Document AI) is a service for parsing structured information from unstructured or semi-structured documents using state-of-the-art Google AI, including natural language processing, computer vision, translation, and AutoML. It helps automate tedious tasks, improve data extraction, and gain deeper insights from documents. The Python client library, currently at version 3.14.0, is part of the actively maintained `google-cloud-python` monorepo, receiving frequent updates.

gcp ai-ml

pip install google-cloud-documentai

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GOOGLE-CLOUD-DOCUM

google-cloud-documentai

gcppythonv3.15.0

Install

5.6s avg

Import

1766ms

Disk

72MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 2.150s · 72.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 5.6s · import 1.382s · 71MB

72MB installed

● package 72MB

Code

Verified usage

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

documentai

✓ from google.cloud import documentai

ClientOptions

✓ from google.api_core.client_options import ClientOptions

This quickstart demonstrates how to process a raw PDF document using a Document AI processor. It requires setting up authentication, a Google Cloud project, and an enabled Document AI processor. Ensure `GOOGLE_APPLICATION_CREDENTIALS` environment variable points to your service account key file, or that Application Default Credentials are configured.

import os import base64 from google.cloud import documentai_v1 as documentai from google.api_core.client_options import ClientOptions project_id = os.environ.get('GCP_PROJECT_ID', 'your-project-id') location = os.environ.get('GCP_REGION', 'us') # Format is 'us' or 'eu' processor_id = os.environ.get('DOCUMENT_AI_PROCESSOR_ID', 'your-processor-id') processor_version_id = os.environ.get('DOCUMENT_AI_PROCESSOR_VERSION_ID', 'rc') # Or specific version, e.g., 'pretrained-ocr-v1.0-2020-09-23' # The full resource name of the processor version # You can also use just 'projects/project_id/locations/location/processors/processor_id' processor_name = f"projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}" # Local file path to the document # For a real application, you'd load actual document bytes. dummy_pdf_content = b"%PDF-1.4\n1 0 obj <</Type/Catalog/Pages 2 0 R>> endobj 2 0 obj <</Type/Pages/Count 1/Kids[3 0 R]>> endobj 3 0 obj <</Type/Page/MediaBox[0 0 612 792]/Contents 4 0 R/Parent 2 0 R>> endobj 4 0 obj <</Length 100>> stream\nBT /F1 24 Tf 100 700 Td (Hello Document AI!) Tj ET\nendstream\nendobj\nxref\n0 5\n0000000000 65535 f\n0000000009 00000 n\n0000000074 00000 n\n0000000155 00000 n\n0000000207 00000 n\ntrailer<</Size 5/Root 1 0 R>>\nstartxref\n313\n%%EOF" mime_type = "application/pdf" # Configure the client with regional endpoint client_options = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com") client = documentai.DocumentProcessorServiceClient(client_options=client_options) # Read the file into memory raw_document = documentai.RawDocument(content=dummy_pdf_content, mime_type=mime_type) # For 'process_document' api: process_options is available in v1beta3 and later request = documentai.ProcessRequest(name=processor_name, raw_document=raw_document) # You must enable the Document AI API in your Google Cloud project before running this code. try: result = client.process_document(request=request) document = result.document print(f"Document processing complete. Text: {document.text}") if document.pages: print(f"Number of pages: {len(document.pages)}") except Exception as e: print(f"Error processing document: {e}") print("Ensure GOOGLE_APPLICATION_CREDENTIALS environment variable is set or other auth method is configured.") print("Also, verify project_id, location, and processor_id are correct and the API is enabled.")

Debug

Known issues

deprecatedDocument AI Human-in-the-Loop (HITL) functionality is deprecated and will no longer be available after January 16, 2025. New customers cannot use it. Existing users must find alternative solutions for human review workflows.

fix

Migrate to a Google Cloud certified partner solution for human review and correction, or implement custom human review workflows.

affects: <= 3.x (before January 16, 2025)

breakingDocument AI processor versions have lifecycles. For example, the Custom Extractor version `pretrained-foundation-model-v1.4-2025-02-05` will no longer be accessible after February 5, 2026. Failing to migrate to a newer processor version can lead to service disruptions.

fix

Regularly check the Document AI release notes for processor version deprecations and plan migrations to newer, supported versions (e.g., `pretrained-foundation-model-v1.5-2025-05-05`).

affects: All versions using specific processor versions

gotchaPython 3.9 is reaching its community End-of-Life (EOL) in October 2025. While `google-cloud-documentai` currently supports Python >= 3.9, other libraries in the `google-cloud-python` ecosystem are beginning to drop support for 3.9. It is recommended to use actively supported Python versions (3.10+) for new development and to plan upgrades for existing systems to ensure continued support and security patches.

fix

Upgrade to Python 3.10 or a newer actively supported version.

affects: < 3.10

gotchaDocument AI's OCR may confuse the digit '0' (zero) with the uppercase letter 'O' in extracted data, especially in mixed alphanumeric fields or from low-quality documents.

fix

Improve input document quality, preprocess images to enhance contrast/sharpness, fine-tune custom extractor models with more specific training data, or implement post-processing logic to correct common confusions.

affects: All versions

gotchaDuring custom processor training, issues like intersecting bounding boxes or empty fields with labels can cause 'internal error' messages, which are often unspecific and difficult to diagnose.

fix

Carefully review labeled documents for overlapping bounding boxes, ensure all labeled fields contain OCRable text, and systematically test training data. Deleting the latest revision of a faulty document from the dataset can sometimes resolve issues but may lead to data loss.

affects: All versions

Errors

Common errors & fixes

Application default credentials are not available.

The application cannot find valid Google Cloud authentication credentials, or the service account used lacks the necessary IAM permissions for Document AI operations.

fix

Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key JSON file (`export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json`), or authenticate locally using `gcloud auth application-default login`. Ensure the service account has roles like 'Document AI User' or 'Document AI Viewer'.

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

The `google-cloud-documentai` Python client library is not installed in your current environment, or there is a naming conflict with an older `google-cloud` meta-package.

fix

Install or upgrade the library using `pip install --upgrade google-cloud-documentai`. If the error persists, ensure you don't have the deprecated `google-cloud` package installed (`pip uninstall google-cloud`).

google.api_core.exceptions.InvalidArgument: 400 Request contains an invalid argument.

A parameter in your Document AI API request, such as the `processor_name`, GCS URI, `mime_type`, or document content itself, is malformed, invalid, or does not match the expected format or type for the processor.

fix

Verify that your `processor_name` is in the correct format (`projects/{project_id}/locations/{location}/processors/{processor_id}`), GCS URIs are accessible and correctly formatted, `mime_type` accurately reflects the document content, and the document is not corrupted or exceeding size limits. Also, ensure the processor type matches the document being sent.

google.api_core.exceptions.NotFound: 404 Not Found: projects/{project_id}/locations/{location}/processors/{processor_id}

The specified Document AI processor, processor version, or a referenced Google Cloud Storage resource (like an input document or output bucket) could not be found, often due to a typo in the ID or path, or the resource not existing in the specified project/location.

fix

Double-check the `project_id`, `location`, `processor_id`, and `processor_version` for typos and confirm they exist in your Google Cloud project. Ensure the Document AI API is enabled in the project, and any referenced GCS paths are correct and accessible.

Invalid location: '{region}' must match '{expected_region}'

The Document AI client is attempting to connect to a processor in a different region than the one specified or implied by the client's default endpoint configuration.

fix

Explicitly set the `api_endpoint` in the `DocumentProcessorServiceClient` client options to match the region where your processor is located. For example, for a processor in 'eu', initialize the client with `client_options=ClientOptions(api_endpoint='eu-documentai.googleapis.com')`.

Upgrade

Version history

3.15.0latest on PyPI · released Jun 3, 2026

Audit

Dependencies

PythonrequiredRequires Python >= 3.9.

google-cloud-storageoptionalRequired for processing documents from or writing results to Google Cloud Storage buckets.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

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

packagehttps://pypi.org/project/google-cloud-documentai/ ↗

homepagehttps://cloud.google.com/document-ai ↗