{"id":3411,"library":"azure-ai-formrecognizer","title":"Azure AI Form Recognizer Client Library","description":"The Azure AI Form Recognizer client library for Python, now part of Azure AI Document Intelligence, uses machine learning to analyze text and structured data from documents. It provides capabilities for layout extraction, prebuilt models (e.g., receipts, invoices, identity documents), custom model building and analysis, and document classification. This library is actively maintained as part of the broader Azure SDK for Python and typically sees regular updates with new service features and bug fixes.","status":"active","version":"3.3.3","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python","tags":["azure","ai","form-recognizer","document-intelligence","ocr","document-analysis"],"install":[{"cmd":"pip install azure-ai-formrecognizer","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.8 or later.","package":"python","optional":false},{"reason":"Required for using asynchronous APIs.","package":"aiohttp","optional":true}],"imports":[{"note":"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).","wrong":"from azure.ai.formrecognizer import FormRecognizerClient","symbol":"DocumentAnalysisClient","correct":"from azure.ai.formrecognizer import DocumentAnalysisClient"},{"note":"Used for building, composing, and managing custom document models.","symbol":"DocumentModelAdministrationClient","correct":"from azure.ai.formrecognizer import DocumentModelAdministrationClient"},{"note":"Used for authenticating with an API key.","symbol":"AzureKeyCredential","correct":"from azure.core.credentials import AzureKeyCredential"}],"quickstart":{"code":"import os\nfrom azure.ai.formrecognizer import DocumentAnalysisClient\nfrom azure.core.credentials import AzureKeyCredential\n\n# Set these environment variables for authentication\nendpoint = os.environ.get('AZURE_FORM_RECOGNIZER_ENDPOINT', 'YOUR_FORM_RECOGNIZER_ENDPOINT')\nkey = os.environ.get('AZURE_FORM_RECOGNIZER_KEY', 'YOUR_FORM_RECOGNIZER_KEY')\n\nif endpoint == 'YOUR_FORM_RECOGNIZER_ENDPOINT' or key == 'YOUR_FORM_RECOGNIZER_KEY':\n    print(\"Please set the AZURE_FORM_RECOGNIZER_ENDPOINT and AZURE_FORM_RECOGNIZER_KEY environment variables.\")\n    exit()\n\n# Example document URL (replace with your own)\ndocument_url = \"https://raw.githubusercontent.com/Azure-Samples/cognitive-services-quickstart-code/master/python/FormRecognizer/rest/sample_data/Form_1.jpg\"\n\ndef analyze_general_document():\n    document_analysis_client = DocumentAnalysisClient(\n        endpoint=endpoint, credential=AzureKeyCredential(key)\n    )\n\n    print(f\"Analyzing document from: {document_url}\")\n    # Use the prebuilt-document model for general document analysis\n    poller = document_analysis_client.begin_analyze_document_from_url(\n        \"prebuilt-document\", document_url\n    )\n    result = poller.result()\n\n    if result.documents:\n        for idx, doc in enumerate(result.documents):\n            print(f\"----Detected Document #{idx+1}-----\")\n            print(f\"Document type: {doc.doc_type}\")\n            if doc.fields:\n                print(\"Fields:\")\n                for name, field in doc.fields.items():\n                    field_value = field.value if field.value else field.content\n                    print(f\"  {name}: {field_value} (Confidence: {field.confidence:.2f})\")\n    else:\n        print(\"No documents detected.\")\n\n    print(\"---Analysis complete.---\")\n\nif __name__ == \"__main__\":\n    analyze_general_document()\n","lang":"python","description":"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."},"warnings":[{"fix":"Migrate client instantiation from `FormRecognizerClient` to `DocumentAnalysisClient` or `DocumentModelAdministrationClient` as per service API version. Refer to migration guides for detailed changes.","message":"For 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.","severity":"breaking","affected_versions":">=3.2.0 (SDK) / >=2022-08-31 (Service API)"},{"fix":"Review 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.","message":"As 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.","severity":"breaking","affected_versions":">=3.3.0"},{"fix":"Be aware of the name change when consulting documentation or troubleshooting. The underlying functionality remains the same.","message":"The 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'.","severity":"deprecated","affected_versions":"All"},{"fix":"Upgrade your Python environment to 3.8 or later.","message":"As of `azure-ai-formrecognizer` version 3.3.3, Python 3.7 is no longer supported. The minimum required Python version is 3.8.","severity":"breaking","affected_versions":">=3.3.3"},{"fix":"Verify 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.","message":"Common '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).","severity":"gotcha","affected_versions":"All"},{"fix":"Validate 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.","message":"Errors 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).","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}