LayoutParser

0.3.4 · active · verified Thu Apr 16

LayoutParser is a unified toolkit for Deep Learning Based Document Image Analysis, providing a comprehensive set of tools for tasks like document layout detection, OCR, and visualization. It is currently at version 0.3.4 and maintains an active development cycle with regular patch releases and significant minor/major updates that introduce new models and backend support.

Common errors

```
ModuleNotFoundError: No module named 'detectron2'
```
cause You attempted to use a Detectron2-based model (e.g., `Detectron2LayoutModel` or a model requiring Detectron2 via `AutoLayoutModel`) without installing the `detectron2` dependency.

fix Install LayoutParser with the Detectron2 extras: `pip install 'layoutparser[detectron2]'` or `pip install 'layoutparser[all]'`.
```
FileNotFoundError: [Errno 2] No such file or directory: 'tesseract'
```
cause The Python `pytesseract` library is installed, but the Tesseract OCR executable is not found in your system's PATH.

fix Install 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'
```
cause 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.

fix Double-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`).

Warnings

gotcha LayoutParser relies on various deep learning backends and OCR engines. The minimal `pip install layoutparser` only installs core dependencies. For full functionality (e.g., using Detectron2 models or Tesseract OCR), you must install with 'extras' like `layoutparser[all]`, `layoutparser[detectron2]`, or `layoutparser[tesseract]`.
Fix: Always use `pip install 'layoutparser[all]'` for a comprehensive setup, or `pip install 'layoutparser[backend_name]'` for specific needs. Refer to the official installation guide for a full list of extras.
breaking Starting from v0.3.0, LayoutParser introduced `AutoLayoutModel` for multi-backend support. While direct `Detectron2LayoutModel` usage is still possible, `AutoLayoutModel` is the recommended and more flexible way to load models. Using older explicit model classes might require more configuration or become less idiomatic.
Fix: Migrate model loading to `lp.AutoLayoutModel(model_path="lp://...")`. This simplifies model instantiation and allows easier switching between backends.
gotcha When using `TesseractAgent` for OCR, the Tesseract OCR engine must be installed on your system (not just the Python `pytesseract` package) and added to your system's PATH. This is a common oversight.
Fix: Install Tesseract OCR engine globally on your operating system (e.g., `sudo apt-get install tesseract-ocr` on Debian/Ubuntu, or follow instructions for Windows/macOS). Ensure its executable is accessible via your system's PATH.

Install

pip install layoutparser Minimal installation (core library)
pip install 'layoutparser[all]' Full installation (includes Detectron2, Tesseract, GCV, PaddleOCR dependencies)
pip install 'layoutparser[detectron2]' 'layoutparser[tesseract]' Example: Install with Detectron2 models and Tesseract OCR

Imports

layoutparser
```
import layoutparser as lp
```
Standard convention for importing the library.
Image
wrong:
```
from PIL import Image
```
correct:
```
from layoutparser 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.

Quickstart

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()

view raw JSON →