Install & Compatibility
Where this runs
tested against v0.3.4 · 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.930 runs
build_error
glibcpy 3.10–3.930 runs
installs and imports cleanly · install 17.2s · import 0.102s · 570MB
575MB installed
● package 575MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
layoutparser
✓ import layoutparser as lp
Standard convention for importing the library.
Image
✓ from layoutparser import Image
✗ from PIL import Image
Use layoutparser.Image for full compatibility with the library's functions, although PIL.Image can often be converted.
AutoLayoutModel
✓ from layoutparser import AutoLayoutModel
Introduced in v0.3.0, the recommended way to load pre-trained models from various backends.
Detectron2LayoutModel
✓ from layoutparser import Detectron2LayoutModel
Explicit class for Detectron2 models. Still valid, but AutoLayoutModel is often more convenient since v0.3.0.
TesseractAgent
✓ from layoutparser import TesseractAgent
Class for integrating Tesseract OCR.
draw_box
✓ from layoutparser import draw_box
Utility function for visualizing layout elements.
This quickstart demonstrates how to load an image from a URL, use `AutoLayoutModel` (recommended for v0.3.0+) to detect the document layout, and print the detected blocks. For visualization, ensure `matplotlib` is installed and uncomment the relevant lines.
import layoutparser as lp
from PIL import Image
import io
import requests
# Download a sample image
image_url = "https://layout-parser.github.io/assets/images/publaynet.png"
response = requests.get(image_url)
image_bytes = io.BytesIO(response.content)
# Load the image using PIL, then convert to layoutparser.Image
pil_image = Image.open(image_bytes)
lp_image = lp.Image(pil_image)
# Load a pre-trained layout model (using AutoLayoutModel since v0.3.0+)
# Requires 'layoutparser[detectron2]' installed.
model = lp.AutoLayoutModel(model_path="lp://PubLayNet/faster_rcnn_R_50_FPN_3x/config")
# Detect the layout
layout = model.detect(lp_image)
# Print detected blocks and their types
print(f"Detected {len(layout)} blocks:")
for block in layout:
print(f" - Type: {block.type}, Box: {block.coordinates}")
# (Optional) Visualize the layout
# You might need matplotlib for this to display the image
# import matplotlib.pyplot as plt
# fig = lp.draw_box(lp_image, layout, box_width=3)
# plt.imshow(fig)
# plt.show()
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'detectron2'
You attempted to use a Detectron2-based model (e.g., `Detectron2LayoutModel` or a model requiring Detectron2 via `AutoLayoutModel`) without installing the `detectron2` dependency.
fixInstall LayoutParser with the Detectron2 extras: `pip install 'layoutparser[detectron2]'` or `pip install 'layoutparser[all]'`.
FileNotFoundError: [Errno 2] No such file or directory: 'tesseract'
The Python `pytesseract` library is installed, but the Tesseract OCR executable is not found in your system's PATH.
fixInstall the Tesseract OCR engine on your operating system (e.g., `brew install tesseract` on macOS, or see Tesseract's official documentation for other OSes) and ensure it's added to your system's PATH environment variable.
AttributeError: 'NoneType' object has no attribute 'detect'
This usually happens when a layout model fails to load correctly, resulting in the model object being `None`. Common reasons include incorrect `model_path` (or `config_path`), missing dependencies for the chosen backend, or a corrupted model cache.
fixDouble-check your `model_path` string for typos. Ensure all necessary dependencies for that specific model backend (e.g., `detectron2` for Detectron2 models) are installed using the correct `layoutparser` extras. Clear the LayoutParser model cache if you suspect corruption (usually in `~/.cache/layoutparser`).
Upgrade
Version history
0.3.4latest on PyPI · released Apr 6, 2022
Audit
Dependencies
torchrequiredCore deep learning framework dependency for many models.
torchvisionrequiredComputer vision utilities, complements torch.
PillowrequiredImage processing library.
numpyrequiredNumerical computing.
opencv-pythonrequiredOpenCV bindings for image operations.
detectron2optionalRequired for using Detectron2-based layout models (e.g., PubLayNet).
pytesseractoptionalRequired for using the Tesseract OCR agent.
google-cloud-visionoptionalRequired for using the Google Cloud Vision OCR agent.
paddleocroptionalRequired for using PaddleDetection-based layout models.