Install & Compatibility
Where this runs
tested against v1.2.40 · 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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Pipeline
✓ from unstructured_ingest.pipeline.pipeline import Pipeline
✗ from unstructured_ingest.v2.pipeline.pipeline import Pipeline
As of v0.7.0, the 'v2' calling pattern moved up one level in the package, making the direct import the correct one.
ProcessorConfig
✓ from unstructured_ingest.interfaces import ProcessorConfig
✗ from unstructured_ingest.v2.interfaces import ProcessorConfig
The 'v2' namespace was removed from the import path in v0.7.0.
LocalIndexerConfig
✓ from unstructured_ingest.connector.fsspec.local import LocalIndexerConfig
✗ from unstructured_ingest.v2.processes.connectors.local import LocalIndexerConfig
The 'v2' namespace was removed, and import paths were restructured in v0.7.0. Newer versions use `connector` instead of `processes.connectors`.
This quickstart demonstrates how to set up a basic local-to-local ingestion pipeline using `unstructured-ingest`. It indexes a local text file, partitions it, chunks it by title, and uploads the processed output to another local directory. It shows how to configure the pipeline programmatically and highlights where to enable API-based processing and embedding providers if needed.
import os
import tempfile
from unstructured_ingest.pipeline.pipeline import Pipeline
from unstructured_ingest.interfaces import ProcessorConfig
from unstructured_ingest.connector.fsspec.local import (
LocalIndexerConfig,
LocalConnectionConfig,
LocalDownloaderConfig,
LocalUploaderConfig
)
from unstructured_ingest.processor import (
PartitionerConfig,
ChunkerConfig,
EmbedderConfig
)
# Create a dummy input file and directory
input_dir = tempfile.mkdtemp()
output_dir = tempfile.mkdtemp()
with open(os.path.join(input_dir, "example.txt"), "w") as f:
f.write("This is a test document.\nIt has multiple lines.")
print(f"Processing files from: {input_dir}")
print(f"Output will be saved to: {output_dir}")
# Set UNSTRUCTURED_API_KEY and UNSTRUCTURED_API_URL if using Unstructured API
# os.environ["UNSTRUCTURED_API_KEY"] = os.environ.get("UNSTRUCTURED_API_KEY", "")
# os.environ["UNSTRUCTURED_API_URL"] = os.environ.get("UNSTRUCTURED_API_URL", "")
pipeline = Pipeline.from_configs(
context=ProcessorConfig(
output_dir=output_dir,
verbose=True,
num_processes=2
),
indexer_config=LocalIndexerConfig(input_path=input_dir),
downloader_config=LocalDownloaderConfig(),
source_connection_config=LocalConnectionConfig(),
partitioner_config=PartitionerConfig(
strategy="auto",
# partition_by_api=True, # Uncomment to use Unstructured API
# api_key=os.environ.get("UNSTRUCTURED_API_KEY"),
# partition_endpoint=os.environ.get("UNSTRUCTURED_API_URL"),
),
chunker_config=ChunkerConfig(chunk_strategy="by_title"),
# embedder_config=EmbedderConfig(provider="huggingface"), # Requires "unstructured-ingest[huggingface]"
uploader_config=LocalUploaderConfig(output_dir=output_dir)
)
pipeline.run()
print("Ingestion complete. Check output directory for processed files.")
# Clean up (optional)
# import shutil
# shutil.rmtree(input_dir)
# shutil.rmtree(output_dir)
unstructured-ingest --version
Errors
Common errors & fixes
unstructured_ingest.error.PartitionError: Error in partitioning content: Invalid file /path/to/file. The FileType.UNK file type is not supported in partition.
The input file type is not recognized or is not supported by the currently installed dependencies. Often occurs with PDFs, DOCX, or other complex formats without their respective 'extra' dependencies.
fixInstall the necessary extra dependencies for the file type. For example, for PDFs, run `pip install "unstructured-ingest[pdf]"`. For general troubleshooting, ensure `libmagic-dev`, `poppler-utils`, and `tesseract-ocr` are installed as system dependencies.
ModuleNotFoundError: No module named 'unstructured_ingest.v2.pipeline'
This error occurs in versions 0.7.0 and later if you are using the old 'v2' import path which was removed in a breaking change.
fixUpdate your import statements. Remove `.v2` from the import path. For example, change `from unstructured_ingest.v2.pipeline.pipeline import Pipeline` to `from unstructured_ingest.pipeline.pipeline import Pipeline`.
requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: https://api.unstructuredapp.io/general/v0/general/partition
This typically means an invalid or missing API key and/or API URL when attempting to use the Unstructured API for processing.
fixEnsure `UNSTRUCTURED_API_KEY` and `UNSTRUCTURED_API_URL` (or `partition_endpoint`) environment variables are correctly set and contain valid credentials from your Unstructured account. Double-check that `partition_by_api=True` is correctly configured if you intend to use the API.
Upgrade
Version history
1.6.12latest on PyPI · released Jun 8, 2026
Audit
Dependencies
unstructuredrequiredCore library for partitioning and processing documents.
fsspecrequiredRequired for local file system operations.
various_extrasoptionalSpecific connectors (e.g., 'pdf', 's3', 'huggingface') require their own extra dependencies for functionality.