Install & Compatibility
Where this runs
tested against v0.6.3 · 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.9
✕ build_error
✓ 14.25s
58MB installed
● package 58MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PDFText
✓ import pdftext
✗ from pdftext import PDFText
This quickstart demonstrates how to initialize `PDFText` with a PDF file, extract the full text, retrieve text as structured blocks and lines, and extract tables. It assumes a PDF file named 'example.pdf' exists at the specified path for successful execution.
import os
from pdftext import PDFText
# Assuming 'example.pdf' is in the same directory
# For a real application, replace with a valid path to your PDF file
pdf_path = os.path.join(os.path.dirname(__file__), 'example.pdf') # Replace or create example.pdf
# Create a dummy PDF for demonstration if it doesn't exist
# In a real scenario, you'd have your actual PDF here.
# For a proper quickstart, you'd need a real PDF. This is just to make it runnable.
# For local testing, ensure 'example.pdf' exists.
# You can create a simple one: print('Hello PDF') > example.pdf (then convert to actual PDF)
# --- This part requires an actual PDF file ---
# To make this truly runnable for testing, one would need to create a dummy PDF file
# or specify a path to an existing one.
# For local testing, ensure a file named 'example.pdf' exists in the script's directory.
# For a quick dummy, if you have FPDF installed:
# from fpdf import FPDF
# pdf = FPDF()
# pdf.add_page()
# pdf.set_font('Arial', 'B', 16)
# pdf.cell(40, 10, 'Hello, pdftext!')
# pdf.output(pdf_path)
# Let's assume pdf_path points to an existing PDF for this example.
# If you don't have an example.pdf, this will fail with FileNotFoundError.
try:
# Initialize PDFText with the path to your PDF
pdf_processor = PDFText(pdf_path)
# Extract all text as a single string
full_text = pdf_processor.as_text()
print("--- Full Text ---")
print(full_text)
# Extract text as blocks
text_blocks = pdf_processor.as_blocks()
print("\n--- Text Blocks ---")
for i, block in enumerate(text_blocks[:2]): # Print first 2 blocks
print(f"Block {i+1}: {block.text[:100]}...")
# Extract text as lines (for detailed layout analysis)
text_lines = pdf_processor.as_lines()
print("\n--- Text Lines (first 5) ---")
for i, line in enumerate(text_lines[:5]):
print(f"Line {i+1}: {line.text}")
# Extract tables (if any)
tables = pdf_processor.as_tables()
if tables:
print("\n--- Tables (first) ---")
print(tables[0].to_csv())
else:
print("\nNo tables found.")
except FileNotFoundError:
print(f"Error: PDF file not found at {pdf_path}. Please create or specify a valid PDF.")
except Exception as e:
print(f"An error occurred: {e}")
pdftext --version
Debug
Known issues
breakingVersion 0.4.0 introduced a significant change in text segmentation, moving from a decision tree to a heuristic-based approach. This may result in different text output, especially regarding how spans, lines, and blocks are segmented compared to previous versions.fixIf migrating from <0.4.0, carefully review the extracted text for critical PDFs to ensure segmentation changes do not negatively impact your application. Adjust post-processing logic if necessary.
affects: >=0.4.0
gotchaThe library pins specific versions of its core dependency, `pypdfium2` (e.g., v0.4.1 pinned to a previous version due to a bug). Using an incompatible `pypdfium2` version in your environment can lead to errors or incorrect text extraction.fixAlways install `pdftext` using `pip install pdftext` to ensure compatible dependency versions are installed. If issues arise, check `pyproject.toml` or `setup.py` for the exact `pypdfium2` version range and ensure your environment matches it. Reinstalling `pypdfium2` specifically might resolve conflicts: `pip install --force-reinstall pypdfium2`.
affects: All versions, especially >=0.4.1
gotchaMinor versions, like v0.6.2 and v0.6.3, introduce changes to text span breaking (e.g., more aggressive breaking on newlines) and rotation issue fixes. These improvements, while beneficial, can slightly alter the resulting extracted text structure or content for some PDFs.fixFor applications sensitive to exact text output or layout, it's advisable to perform regression testing on your critical PDF documents after upgrading `pdftext` to these or newer versions to ensure consistency.
affects: >=0.6.2
Upgrade
Version history
0.6.3latest on PyPI · released Jun 11, 2025
Audit
Dependencies
pypdfium2requiredCore PDF rendering and text extraction backend; specific versions have caused issues in the past.
scipyrequiredUsed for numerical operations and data analysis in text processing.
nltkrequiredNatural Language Toolkit, used for text processing tasks.