Install & Compatibility
Where this runs
tested against v1.2.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
py 3.10
✕ build_error
1/2 runs
py 3.11
✕ build_error
1/2 runs
py 3.12
✕ build_error
1/2 runs
py 3.13
✕ build_error
1/2 runs
py 3.9
✕ build_error
✕ timeout
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DocumentLayout
✓ from unstructured_inference.inference.layout import DocumentLayout
get_model
✓ from unstructured_inference.models.base import get_model
This quickstart demonstrates how to load a PDF document and extract its layout elements using the default inference model. It creates a dummy PDF for immediate execution. In a real application, you would replace `temp_pdf_path` with the path to your actual PDF file. The output includes the detected element types and their truncated text content.
import os
import tempfile
# Create a dummy PDF file for demonstration
# In a real scenario, you would provide the path to your actual PDF.
with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as temp_pdf:
temp_pdf_path = temp_pdf.name
temp_pdf.write(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/Parent 2 0 R/MediaBox[0 0 612 792]/Contents 4 0 R>>endobj 4 0 obj<</Length 41>>stream\nBT /F1 24 Tf 100 700 Td (Hello Unstructured!) Tj ET\nendstream\nendobj\nxref\n0 5\n0000000000 65535 f\n0000000009 00000 n\n0000000055 00000 n\n0000000108 00000 n\n0000000201 00000 n\ntrailer<</Size 5/Root 1 0 R>>startxref\n294\n%%EOF")
from unstructured_inference.inference.layout import DocumentLayout
try:
# Perform layout parsing on the document
# For real use, replace temp_pdf_path with your PDF file path.
layout = DocumentLayout.from_file(temp_pdf_path)
print(f"Found {len(layout.pages)} page(s) in the document.")
for i, page in enumerate(layout.pages):
print(f"--- Page {i+1} ---")
for element in page.elements:
print(f"Element Type: {element.type}, Text: {element.text[:50]}...")
# You can also access bounding box, model name, etc.
# print(f" Bounding Box: {element.bbox}, Model: {element.detectron_model_name}")
finally:
# Clean up the dummy PDF file
os.remove(temp_pdf_path)
Debug
Known issues
gotchaDetectron2 is a crucial dependency for using many layout parsing models within unstructured-inference, particularly those from the layoutparser model zoo. It is NOT automatically installed with `pip install unstructured-inference` and its installation can be complex, especially on Windows, where it's not officially supported. Users on macOS/Linux may need to build it from source.fixRefer to the Unstructured-IO documentation or Detectron2's installation guide for specific instructions. For macOS/Linux, `pip install 'git+https://github.com/facebookresearch/detectron2.git@57bdb21249d5418c130d54e2ebdc94dda7a4c01a'` is often required. Windows users may need to find community-supported workarounds or use WSL.
affects: All versions
breakingThe library has a strict Python version requirement, currently supporting Python 3.12 only. Using other Python versions will lead to installation or runtime errors.fixEnsure your environment is running Python 3.12. Consider using virtual environments (like `venv` or `uv`) to manage specific Python versions for your projects.
affects: 1.6.0+
gotchaWhen `unstructured-inference` is used in conjunction with the main `unstructured` library, it's crucial to keep both packages synchronized to avoid unexpected behavior or errors, as `unstructured-inference` provides the underlying model capabilities for `unstructured`'s partitioning bricks.fixWhen updating `unstructured`, ensure `unstructured-inference` is also updated to a compatible version. Using `pip install "unstructured[all-docs]"` (if using `unstructured`) often helps ensure dependent packages are aligned.
affects: All versions
gotchaThere have been reports of issues with table extraction functionality in recent versions of `unstructured-inference`, where the latest versions may not extract tables as effectively as older versions.fixIf experiencing issues with table extraction, consult the GitHub issues for `unstructured-inference` for potential workarounds or targeted fixes. Downgrading to a previous version known to work with table extraction might be a temporary solution, but use with caution regarding other potential regressions.
affects: 1.6.x (as of current observation)
deprecatedWhen using `unstructured`'s `partition` function with `strategy='hi_res'` (which utilizes `unstructured-inference` models), the `model_name` parameter is deprecated. Users should now use `hi_res_model_name` instead.fixUpdate calls from `partition(..., model_name='yolox')` to `partition(..., hi_res_model_name='yolox')`.
affects: When used via `unstructured` library (unstructured 0.12.x+)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'unstructured_inference.models.detectron2'
The Detectron2 model backend was requested, but its required dependencies were not installed as optional extras.
fixInstall unstructured-inference with the detectron2 extra: `pip install "unstructured-inference[detectron2]"`
ERROR: Could not build wheels for detectron2
Detectron2 has complex installation requirements, often failing due to incompatible PyTorch/CUDA versions or missing system build tools.
fixFirst, manually install PyTorch according to your system's specifications from `https://pytorch.org/get-started/locally/`, then install Detectron2 manually following its instructions from `https://detectron2.readthedocs.io/en/latest/tutorials/install.html`, ensuring compatibility. Finally, install `unstructured-inference`.
ModuleNotFoundError: No module named 'yolox'
The YOLOX model backend was requested, but its required dependencies were not installed as optional extras.
fixInstall unstructured-inference with the yolox extra: `pip install "unstructured-inference[yolox]"`
OSError: [Errno 13] Permission denied: '/root/.cache/unstructured_inference/models/...'
The inference library attempted to download and cache models to a directory where the user process lacks write permissions.
fixSet the `UNSTRUCTURED_CACHE_DIR` environment variable to a writable directory before running your application, e.g., `export UNSTRUCTURED_CACHE_DIR=/tmp/unstructured_cache`.
onnxruntime.capi.onnxruntime_pybind11_state.Fail: [ONNXRuntimeError] : 1 : FAIL : Load model failed:
The ONNX model file is corrupted, incompatible with the installed onnxruntime version, or onnxruntime itself failed to initialize.
fixEnsure `unstructured-inference` and `onnxruntime` are up-to-date. If the issue persists, clear the `UNSTRUCTURED_CACHE_DIR` (or the default cache location) to force a re-download of models.
Upgrade
Version history
1.6.13latest on PyPI · released Jun 11, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
detectron2optionalRequired for using models from the layoutparser model zoo. Not automatically installed and has complex installation, especially on Windows.