Registry /
azure / azure-ai-documentintelligence
Install & Compatibility
Where this runs
tested against v1.0.2 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.459s · 24.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.4s · import 0.412s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DocumentIntelligenceClient
✓ from azure.ai.documentintelligence import DocumentIntelligenceClient
✗ from azure.ai.formrecognizer import FormRecognizerClient
The package and client names were rebranded from 'Form Recognizer' to 'Document Intelligence'.
DocumentIntelligenceAdministrationClient
✓ from azure.ai.documentintelligence import DocumentIntelligenceAdministrationClient
✗ from azure.ai.formrecognizer import DocumentModelAdministrationClient
The package and client names were rebranded from 'Form Recognizer' to 'Document Intelligence'.
AzureKeyCredential
✓ from azure.core.credentials import AzureKeyCredential
Demonstrates how to initialize a `DocumentIntelligenceClient` with an endpoint and API key, and then use it to analyze a document from a URL using a prebuilt model. It iterates through the extracted fields and prints their content and confidence.
import os
from azure.ai.documentintelligence import DocumentIntelligenceClient
from azure.core.credentials import AzureKeyCredential
# Set your Document Intelligence endpoint and key as environment variables
# e.g., AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT and AZURE_DOCUMENT_INTELLIGENCE_KEY
endpoint = os.environ.get("AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT", "<your-endpoint>")
key = os.environ.get("AZURE_DOCUMENT_INTELLIGENCE_KEY", "<your-key>")
if endpoint == "<your-endpoint>" or key == "<your-key>":
print("Please set the AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT and AZURE_DOCUMENT_INTELLIGENCE_KEY environment variables.")
print("You can find these in your Azure portal under your Document Intelligence resource's 'Keys and Endpoint' section.")
else:
document_url = "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/sdk/documentintelligence/azure-ai-documentintelligence/samples/sample_forms/forms/Invoice_1.pdf"
document_intelligence_client = DocumentIntelligenceClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
print(f"Analyzing document from URL: {document_url}")
# Use 'prebuilt-invoice' for invoices, 'prebuilt-receipt' for receipts, etc.
# Or use your custom model_id for custom models
poller = document_intelligence_client.begin_analyze_document_from_url(
"prebuilt-invoice", document_url
)
result = poller.result()
if result.documents:
for idx, document in enumerate(result.documents):
print(f"\n--- Document {idx + 1} Analysis ---")
if document.doc_type:
print(f" Document type: {document.doc_type}")
if document.fields:
print(" Extracted Fields:")
for name, field in document.fields.items():
if field.content:
print(f" {name}: {field.content} (Confidence: {field.confidence:.2f})")
else:
print("No documents found in the analysis result.")
Debug
Known issues
breakingThe package and client library were rebranded from `azure-ai-formrecognizer` to `azure-ai-documentintelligence`. This requires updating package imports and client class names (e.g., `FormRecognizerClient` to `DocumentIntelligenceClient`, `DocumentModelAdministrationClient` to `DocumentIntelligenceAdministrationClient`).fixUpdate your `pip install` command, change import statements, and update client instantiation to use the new names (e.g., `DocumentIntelligenceClient`). Refer to the official migration guide.
affects: <1.0.0
breakingThe structure of the `AnalyzeResult` object and how to access extracted data changed significantly in version 1.0.0 (aligned with service API 2024-11-30). Direct access to properties like `.forms` or `.receipts` is no longer available. Instead, results are accessed via `result.documents` which is a list of `Document` objects.fixRefactor your code to iterate through `poller.result().documents` and then access `document.fields` to retrieve extracted key-value pairs or other information. Consult the latest quickstart examples for the new result parsing pattern.
affects: <1.0.0
gotchaAsynchronous (async) client operations require the `aiohttp` package to be installed separately (`pip install azure-ai-documentintelligence[aiohttp]`). Mixing synchronous and asynchronous clients or methods can lead to runtime errors or unexpected behavior.fixEnsure `aiohttp` is installed for async use. When using async clients (`AsyncDocumentIntelligenceClient`), ensure all related operations (`await client.begin_analyze_document_from_url(...)`) are also `await`-ed within an `async` function.
affects: >=1.0.0
gotchaAuthentication issues are common. Using a regional endpoint with Azure Active Directory (AAD) authentication is not supported; a custom subdomain name for your resource is required for AAD. Ensure `AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT` and `AZURE_DOCUMENT_INTELLIGENCE_KEY` environment variables are correctly set or provided to `DocumentIntelligenceClient` via `AzureKeyCredential`.fixVerify that your endpoint and key are correct and correspond to your Document Intelligence resource. For AAD authentication, use a custom subdomain. Always check the official documentation for the latest authentication recommendations.
affects: All
deprecatedOlder API versions and specific models are being deprecated. For example, the `2022-08-31` API version and the `prebuilt-document` model are deprecated in favor of newer API versions (e.g., `2024-11-30`) and models like `prebuilt-layout` with `features=keyValuePairs`.fixAlways use the latest stable SDK version. Refer to the Azure AI Document Intelligence documentation for the current recommended API version and models. Migrate any code using deprecated API versions or models as per the official migration guides.
affects: <1.0.0 (for older APIs/models)
gotchaWhen training and using custom models, remember to pass the `model_id` (an alphanumeric string or UUID), not the human-readable model name, to methods like `begin_analyze_document` or `begin_analyze_document_from_url`.fixDouble-check that you are using the correct `model_id` obtained after training your custom model, usually found in the Azure portal or Document Intelligence Studio.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure-ai-documentintelligence'
The 'azure-ai-documentintelligence' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install azure-ai-documentintelligence'.
NameError: name 'AnalyzeDocumentRequest' is not defined
The 'AnalyzeDocumentRequest' class is not defined in the current scope, possibly due to incorrect import or missing definition.
fixEnsure that 'AnalyzeDocumentRequest' is correctly imported or defined in your code.
InvalidRequest: Invalid request.
The request sent to the Azure AI Document Intelligence service is malformed or contains invalid parameters.
fixReview the request parameters and ensure they conform to the API specifications.
InvalidContent: The file format is unsupported or corrupted.
The document provided is either in an unsupported format or is corrupted.
fixVerify that the document is in a supported format and is not corrupted before processing.
InvalidContentDimensions: The input image dimensions are out of range.
The dimensions of the input image exceed the supported size limits.
fixResize the image to fit within the supported dimensions as specified in the documentation.
Upgrade
Version history
1.0.2latest on PyPI · released Mar 27, 2025
Audit
Dependencies
azure-corerequiredCore functionalities for Azure SDK clients.
azure-commonrequiredCommon utilities for Azure SDKs.
aiohttpoptionalRequired for asynchronous client operations.