Registry /
azure / azure-ai-formrecognizer
Install & Compatibility
Where this runs
tested against v3.3.3 · 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.958s · 29.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.9s · import 0.864s · 30MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DocumentAnalysisClient
✓ from azure.ai.formrecognizer import DocumentAnalysisClient
✗ from azure.ai.formrecognizer import FormRecognizerClient
DocumentAnalysisClient is the primary client for API versions 2022-08-31 and higher (default for 3.x+ SDKs). FormRecognizerClient is for older API versions (v2.1 and below).
DocumentModelAdministrationClient
✓ from azure.ai.formrecognizer import DocumentModelAdministrationClient
Used for building, composing, and managing custom document models.
AzureKeyCredential
✓ from azure.core.credentials import AzureKeyCredential
Used for authenticating with an API key.
This quickstart demonstrates how to create a DocumentAnalysisClient, authenticate using an API key, and analyze a document from a URL using the 'prebuilt-document' model to extract general key-value pairs and other structural information. Remember to replace placeholder endpoint and key values with your actual Azure Form Recognizer resource credentials and provide a URL to your document.
import os
from azure.ai.formrecognizer import DocumentAnalysisClient
from azure.core.credentials import AzureKeyCredential
# Set these environment variables for authentication
endpoint = os.environ.get('AZURE_FORM_RECOGNIZER_ENDPOINT', 'YOUR_FORM_RECOGNIZER_ENDPOINT')
key = os.environ.get('AZURE_FORM_RECOGNIZER_KEY', 'YOUR_FORM_RECOGNIZER_KEY')
if endpoint == 'YOUR_FORM_RECOGNIZER_ENDPOINT' or key == 'YOUR_FORM_RECOGNIZER_KEY':
print("Please set the AZURE_FORM_RECOGNIZER_ENDPOINT and AZURE_FORM_RECOGNIZER_KEY environment variables.")
exit()
# Example document URL (replace with your own)
document_url = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-quickstart-code/master/python/FormRecognizer/rest/sample_data/Form_1.jpg"
def analyze_general_document():
document_analysis_client = DocumentAnalysisClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
print(f"Analyzing document from: {document_url}")
# Use the prebuilt-document model for general document analysis
poller = document_analysis_client.begin_analyze_document_from_url(
"prebuilt-document", document_url
)
result = poller.result()
if result.documents:
for idx, doc in enumerate(result.documents):
print(f"----Detected Document #{idx+1}-----")
print(f"Document type: {doc.doc_type}")
if doc.fields:
print("Fields:")
for name, field in doc.fields.items():
field_value = field.value if field.value else field.content
print(f" {name}: {field_value} (Confidence: {field.confidence:.2f})")
else:
print("No documents detected.")
print("---Analysis complete.---")
if __name__ == "__main__":
analyze_general_document()
Debug
Known issues
breakingFor API versions 2022-08-31 and later, you must use `DocumentAnalysisClient` and `DocumentModelAdministrationClient`. The older `FormRecognizerClient` is deprecated for these versions and only supports service API versions 2.1 and below.fixMigrate client instantiation from `FormRecognizerClient` to `DocumentAnalysisClient` or `DocumentModelAdministrationClient` as per service API version. Refer to migration guides for detailed changes.
affects: >=3.2.0 (SDK) / >=2022-08-31 (Service API)
breakingAs of SDK version 3.3.0 and service API version 2023-07-31 (now default), several properties and models were removed, including `query_fields` keyword argument, `DocumentPage.images`, `DocumentImage` model, `DocumentPage.annotations`, `DocumentAnnotation` model, and `DocumentKeyValuePair.common_name`. Some `AnalysisFeature` enum members were also renamed.fixReview the official changelog and migration guide for your specific version. Adapt code to use the new add-on capabilities (e.g., `features` parameter for barcodes, formulas, key-value pairs) instead of removed properties.
affects: >=3.3.0
deprecatedThe service name 'Azure Form Recognizer' was officially renamed to 'Azure AI Document Intelligence' in July 2023. While the Python package `azure-ai-formrecognizer` retains its name, documentation and service terminology refer to 'Document Intelligence'.fixBe aware of the name change when consulting documentation or troubleshooting. The underlying functionality remains the same.
affects: All
breakingAs of `azure-ai-formrecognizer` version 3.3.3, Python 3.7 is no longer supported. The minimum required Python version is 3.8.fixUpgrade your Python environment to 3.8 or later.
affects: >=3.3.3
gotchaCommon 'Unauthorized' errors (HTTP 401) often indicate an incorrect endpoint, an invalid or expired subscription key, or attempting Azure Active Directory (AAD) authentication on a regional endpoint (AAD requires a custom subdomain).fixVerify your `endpoint` and `key` against your Azure resource. Ensure the endpoint format is correct (e.g., `https://<your-resource-name>.cognitiveservices.azure.com/`). For AAD, confirm a custom subdomain is used and service principal has 'Cognitive Services User' role.
affects: All
gotchaErrors like 'InvalidContentSourceFormat', 'InvalidContent', or `DecodeError: JSON is invalid` for specific documents can stem from corrupted files, unsupported file types, incorrect SAS URLs, or issues with blob storage paths (e.g., an extra leading '/' in container paths can create a virtual directory that is not recognized).fixValidate document integrity and format. Check SAS token permissions and expiry. Ensure blob storage paths are correct without leading slashes if not intended. For `DecodeError` on long PDFs, try splitting documents or increasing service timeouts if available.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.ai.formrecognizer'
The 'azure-ai-formrecognizer' package is not installed in the Python environment.
fixInstall the package using 'pip install azure-ai-formrecognizer'.
ImportError: cannot import name 'DocumentAnalysisClient' from 'azure.ai.formrecognizer'
The 'DocumentAnalysisClient' class is not available in the installed version of the 'azure-ai-formrecognizer' package.
fixEnsure you have the latest version by running 'pip install --upgrade azure-ai-formrecognizer'.
azure.core.exceptions.HttpResponseError: (1001) Specified model not found or not ready, Model Id: mymodel
The specified model ID does not exist or is not ready for use.
fixVerify the model ID is correct and that the model is trained and ready.
ModuleNotFoundError: No module named 'azure'
The 'azure' package is not installed or the Python environment is not set up correctly.
fixInstall the package using 'pip install azure'.
ModuleNotFoundError: No module named 'azure.ai'
The 'azure-ai' package is not installed in the Python environment.
fixInstall the package using 'pip install azure-ai'.
Upgrade
Version history
3.3.3latest on PyPI · released Apr 9, 2024
Audit
Dependencies
pythonrequiredRequires Python 3.8 or later.
aiohttpoptionalRequired for using asynchronous APIs.