Install & Compatibility
Where this runs
tested against v0.18.32 · 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/3 runs
py 3.12
✕ build_error
1/3 runs
py 3.13
✕ build_error
✓ 80.97s
6349MB installed
● package 6349MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
partition
✓ from unstructured.partition.auto import partition
This is the recommended entry point for automatic file type detection and partitioning.
partition_pdf
✓ from unstructured.partition.pdf import partition_pdf
Use this directly if the file type is known to avoid filetype detection overhead and dependencies.
elements_to_json
✓ from unstructured.staging.base import elements_to_json
Commonly used to convert the list of elements into a JSON output.
This quickstart demonstrates how to use the `partition` function to process a PDF file and extract its constituent elements. It then converts these elements into a JSON format. This requires the `unstructured[pdf]` extra and system dependencies like Poppler and Tesseract for full functionality.
import os
from unstructured.partition.auto import partition
from unstructured.staging.base import elements_to_json
# Create a dummy PDF file for demonstration
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/Parent 2 0 R/MediaBox[0 0 612 792]/Contents 4 0 R/Resources<<>>>>endobj 4 0 obj<</Length 44>>stream\nBT\n/F1 24 Tf\n100 700 Td\n(Hello, Unstructured!) Tj\nET\nendstream\nendobj\nxref\n0 5\n0000000000 65535 f\n0000000009 00000 n\n0000000074 00000 n\n0000000130 00000 n\n0000000302 00000 n\ntrailer<</Size 5/Root 1 0 R>>startxref\n390\n%%EOF"
with open("dummy.pdf", "wb") as f:
f.write(dummy_pdf_content)
# Partition the PDF document
print("Partitioning 'dummy.pdf'...")
elements = partition(filename="dummy.pdf")
# Print the extracted elements
print("\n--- Extracted Elements ---")
for element in elements:
print(f"Type: {type(element).__name__}, Text: {element.text[:75]}...")
# Convert elements to JSON and print
print("\n--- JSON Output ---")
json_output = elements_to_json(elements)
print(json_output)
# Clean up the dummy file
os.remove("dummy.pdf")
unstructured --version
Debug
Known issues
breakingVersion 0.21.0 replaced NLTK with spaCy to remediate CVE-2025-14009. If your project relied on NLTK components used by Unstructured, you might need to update your dependencies or code.fixReview `unstructured` dependency usage. Ensure spaCy models are installed as needed if you were leveraging specific NLP capabilities implicitly through older Unstructured versions.
affects: >=0.21.0
gotchaFull functionality for various document types (e.g., PDFs, images, Office docs) requires installing additional system dependencies (e.g., `libmagic-dev`, `poppler-utils`, `tesseract-ocr`, `libreoffice`, `pandoc`). Without these, some document processing will fail or be limited.fixInstall the recommended system dependencies for the document types you intend to process. Refer to the 'Full Installation' guide in the official documentation for OS-specific instructions.
affects: All versions
gotchaThe open-source library is primarily for prototyping. For production-grade scenarios, Unstructured-IO recommends using their hosted UI or API, which offers greater scalability, robustness, and more advanced features.fixEvaluate your use case: for serious production deployments, consider the Unstructured API or UI. For local prototyping or smaller-scale automation, the open-source library is suitable.
affects: All versions
gotchaElement IDs are SHA-256 hashes by default and are not guaranteed to be unique across different elements with identical text content. This can lead to collisions if used as primary keys.fixPass `unique_element_ids=True` to the `partition` function (e.g., `partition(filename, unique_element_ids=True)`) to generate UUIDs for element IDs, ensuring uniqueness.
affects: All versions
breakingThe telemetry (analytics) opt-out environment variable semantics changed. `DO_NOT_TRACK` and `SCARF_NO_ANALYTICS` now treat any non-empty string value (e.g., 'false', '0', 'no') as an opt-out. Previously, only the exact string 'true' worked.fixTo *not* opt-out (i.e., enable telemetry), unset the environment variable or ensure it is an empty string. To opt-out, set it to any non-empty value (e.g., `export DO_NOT_TRACK=1`).
affects: Recent versions, starting around 0.22.x
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'pdftotext'
The `unstructured` library relies on external system utilities, such as Poppler (for PDFs) or Tesseract (for OCR), which are not installed or are not in your system's PATH.
fixInstall the required system dependencies: for Poppler, use `sudo apt-get install poppler-utils` on Ubuntu/Debian, `brew install poppler` on macOS, or follow specific instructions for Windows.
ModuleNotFoundError: No module named 'pdfminer.high_level'
`unstructured` requires additional Python packages (specified as 'extras') for processing certain file types, and these were not installed with the base `unstructured` package.
fixInstall `unstructured` with the specific extras for the file types you need (e.g., `pip install "unstructured[pdf]"` for PDFs, `pip install "unstructured[docx]"` for Word documents, or `pip install "unstructured[all-docs]"` for most common types).
AttributeError: module 'unstructured' has no attribute 'partition_pdf'
Partitioning functions like `partition_pdf` are located within specific submodules (e.g., `unstructured.partition.pdf`) and must be imported directly from there, not accessed as attributes of the top-level `unstructured` package.
fixImport the function directly from its specific submodule, for example: `from unstructured.partition.pdf import partition_pdf`.
ValueError: File is not a supported file type.
The provided file's mimetype is not recognized by `unstructured`, or the necessary optional dependencies to process that specific file type are missing.
fixEnsure the file is one of the supported types; if it should be supported, verify that `unstructured` was installed with the correct 'extras' (e.g., `pip install "unstructured[xlsx]"`) and check for any missing system dependencies (like Poppler for PDFs).
Upgrade
Version history
0.27.1latest on PyPI · released Aug 21, 2026
Audit
Dependencies
libmagic-devoptionalSystem dependency for filetype detection, highly recommended for `partition` function.
poppler-utilsoptionalSystem dependency for PDF processing (often required with `unstructured[pdf]`).
tesseract-ocroptionalSystem dependency for image and PDF OCR (often required with `unstructured[image]` or `unstructured[pdf]`).
libreofficeoptionalSystem dependency for Microsoft Office document processing (e.g., DOCX, PPTX).
pandocoptionalSystem dependency for EPUB, ODT, and RTF file processing.