Install & Compatibility
Where this runs
tested against v0.42.12 · 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 2.708s · 74.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.5s · import 3.198s · 70MB
57MB installed
● package 57MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
UnstructuredClient
✓ from unstructured_client import UnstructuredClient
PartitionParameters
✓ from unstructured_client.models.shared import PartitionParameters
✗ from unstructured_client import PartitionParameters
Parameters are located in `unstructured_client.models.shared`.
File
✓ from unstructured_client.models.shared import File
✗ from unstructured_client import File
File object definitions are located in `unstructured_client.models.shared`.
This quickstart demonstrates how to initialize the `UnstructuredClient` and partition a local PDF file using the `general.partition` endpoint. It highlights the use of `PartitionParameters` and `File` objects for robust API interaction and emphasizes environment variable-based API key management.
import os
from unstructured_client import UnstructuredClient
from unstructured_client.models.shared import PartitionParameters, File
# --- IMPORTANT: Set your API key environment variable ---
# export UNSTRUCTURED_API_KEY="YOUR_API_KEY"
# Get your key from: https://unstructured.io/api-key
s = UnstructuredClient(
api_key_auth=os.environ.get("UNSTRUCTURED_API_KEY", "")
)
# Create a dummy file for demonstration
try:
with open("example.pdf", "w") as f:
f.write("This is a test document with some text.")
except Exception:
pass # Ignore if it exists or fails for simple dummy file
# Example: Partitioning a local file
try:
with open("example.pdf", "rb") as f:
# Prepare the file as a list of File objects for the API
files = [
File(
content=f.read(),
file_name="example.pdf",
mime_type="application/pdf"
)
]
# Call the partition endpoint with parameters
resp = s.general.partition(
partition_parameters=PartitionParameters(
files=files,
strategy="auto", # 'fast', 'hi_res', 'auto'
coordinates=True, # Include bounding box coordinates
output_format="json" # 'json' (default), 'text'
)
)
# Print the extracted elements
print("Successfully partitioned document.")
for element in resp.elements:
print(f"Type: {element.type}, Text: {element.text[:70]}...")
except FileNotFoundError:
print("Please ensure 'example.pdf' exists in the current directory for this example.")
except Exception as e:
print(f"An error occurred during partitioning: {e}")
if "API Key" in str(e):
print("HINT: Ensure your UNSTRUCTURED_API_KEY environment variable is set correctly.")
elif "401" in str(e) or "403" in str(e):
print("HINT: Check your API key for correctness and permissions.")
Debug
Known issues
gotchaThe `unstructured-client` library is distinct from the `unstructured` library. `unstructured-client` interacts with the Unstructured Cloud API, while the `unstructured` library performs local document processing. Do not confuse their imports or functionalities.fixUse `unstructured-client` for API calls and `unstructured` for local, self-hosted processing. Ensure you import from the correct library (e.g., `from unstructured_client import UnstructuredClient`).
affects: All versions
breakingAPI endpoint parameters and request body structures can change between Unstructured API versions, which the client library wraps. This can lead to breaking changes in your code when upgrading `unstructured-client`.fixAlways refer to the official Unstructured API documentation and the `unstructured-client` changelog for the specific version you are using. Update parameter names and request body formats as per the new specifications. Common changes include how files/URLs are passed or new sub-parameters.
affects: All minor and patch versions, but especially between minor versions (e.g., 0.x to 0.y).
gotchaAuthentication via API Key is mandatory for most Unstructured API endpoints. Failing to set the `UNSTRUCTURED_API_KEY` environment variable or providing an invalid key will result in `401 Unauthorized` or `403 Forbidden` errors.fixObtain your API Key from the Unstructured website and set it as an environment variable (`export UNSTRUCTURED_API_KEY="YOUR_API_KEY"`) before running your application, or pass it directly during client initialization (though environment variables are recommended for security).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'unstructured_client'
The `unstructured-client` Python package has not been installed in your development environment.
fix```bash
pip install unstructured-client
```
unstructured_client.exceptions.UnstructuredClientError: Invalid API Key
The API key provided for authentication is either missing, incorrect, or not authorized for the Unstructured API.
fix```python
import os
from unstructured_client import UnstructuredClient
# Ensure UNSTRUCTURED_API_KEY environment variable is set
# For example: export UNSTRUCTURED_API_KEY="YOUR_API_KEY"
client = UnstructuredClient(api_key_auth=os.getenv("UNSTRUCTURED_API_KEY"))
# Alternatively, pass directly: client = UnstructuredClient(api_key_auth="YOUR_API_KEY")
``` AttributeError: 'UnstructuredClient' object has no attribute 'partition'
You are attempting to call the `partition` method directly on the main `UnstructuredClient` instance, but it is located under the `general` sub-client.
fix```python
from unstructured_client import UnstructuredClient
from unstructured_client.models.shared import PartitionRequest
client = UnstructuredClient(api_key_auth="YOUR_API_KEY")
# Assume 'files' is prepared, e.g., files = [("files", ("example.pdf", b"...", "application/pdf"))]
request = PartitionRequest(files=files)
response = client.general.partition(request) # Correct usage
``` TypeError: partition() missing 1 required positional argument: 'request'
The `client.general.partition` method requires a `PartitionRequest` object as its first argument, which was not provided or constructed incorrectly.
fix```python
from unstructured_client.models.shared import PartitionRequest, PartitionParameters
# Prepare your file data
with open("example.pdf", "rb") as f:
files = [("files", (f.name, f.read(), "application/pdf"))]
# Construct the PartitionRequest object correctly
request = PartitionRequest(
files=files,
# Optional: include partition_parameters if needed
partition_parameters=PartitionParameters(
# hi_res_model_name="yolox"
)
)
# Then pass 'request' to the partition method
# client.general.partition(request)
``` Upgrade
Version history
0.46.2latest on PyPI · released Aug 24, 2026
Audit
Dependencies
No dependency data recorded yet.