Registry / data / pdf2image

pdf2image

JSON →
library1.17.0pypypi✓ verified 24d ago

pdf2image is a Python library that acts as a wrapper around the command-line utilities `pdftoppm` and `pdftocairo` (parts of the Poppler PDF rendering library) to convert PDF documents into a list of PIL Image objects. It provides a convenient Pythonic interface for tasks like document display, data processing, and creating thumbnails. The current version is 1.17.0, and it maintains an active release cadence.

pip install pdf2image
INSTALL
IMPORT
SIG · PDF2IMAGE
P
pdf2image
datapythonv1.17.0
Install
2.2s avg
Import
101ms
Disk
36MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.17.0 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.104s · 37.5MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.2s · import 0.098s · 38MB
36MB installed
● package 36MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

convert_from_path
from pdf2image import convert_from_path
convert_from_bytes
from pdf2image import convert_from_bytes

This quickstart demonstrates converting a PDF file into a list of PIL Image objects using `convert_from_path` and saving each page as a JPEG image. It highlights the use of `output_folder` for efficiency with large PDFs and `fmt` for specifying the output image format. Users must ensure Poppler is installed and correctly configured in their system's PATH for the library to function.

import os import tempfile from pdf2image import convert_from_path # NOTE: For this code to run, you need Poppler installed and in your PATH. # Create a dummy PDF file for the example (replace with your actual PDF path) # This example assumes 'dummy.pdf' exists in the same directory. # In a real scenario, you'd provide the path to an existing PDF. if not os.path.exists('dummy.pdf'): print("Please create a 'dummy.pdf' file in the current directory or provide a valid path.") # Example: Create a simple dummy PDF using a library like ReportLab or manually # For demonstration, we'll simulate a successful conversion if no PDF exists # by skipping the actual conversion and printing a message. # In a real app, you'd handle this error. else: try: with tempfile.TemporaryDirectory() as path: images = convert_from_path( 'dummy.pdf', output_folder=path, fmt='jpeg', dpi=200 ) for i, image in enumerate(images): output_filename = f"output_page_{i+1}.jpeg" image.save(output_filename, 'JPEG') print(f"Saved {output_filename}") print("PDF conversion successful (if 'dummy.pdf' existed and Poppler was configured).") except Exception as e: print(f"An error occurred during PDF conversion: {e}") print("Please ensure Poppler is installed and its 'bin' directory is in your system's PATH.") print("For Windows, you might need to specify poppler_path=r'C:\path\to\poppler\bin' in convert_from_path.")
Debug
Known issues
gotchapdf2image is a wrapper and **requires Poppler command-line utilities** (`pdftoppm` and `pdftocairo`) to be installed on your system. If Poppler is not installed or its `bin` directory is not in your system's PATH, you will encounter `PDFInfoNotInstalledError` or similar issues.
fix
Install Poppler for your operating system (e.g., `sudo apt-get install poppler-utils` on Ubuntu, `brew install poppler` on macOS, or download binaries for Windows and add to PATH). For Windows, consider passing `poppler_path='C:\path\to\poppler\bin'` to `convert_from_path`.
affects: All versions
gotchaConverting large PDF files without specifying an `output_folder` can lead to excessive memory consumption, potentially causing the process to be killed.
fix
Always use the `output_folder` parameter when converting large PDFs: `images = convert_from_path('large.pdf', output_folder=temp_dir_path)`.
affects: All versions
deprecatedVersion 1.13.0 was explicitly deprecated shortly after its release due to an issue with `convert_from_bytes` not respecting the `use_pdftocairo` parameter.
fix
Upgrade to version 1.13.1 or later. The issue was fixed in 1.13.1.
affects: 1.13.0
breakingVersion 1.12.0 introduced a deadlock on Windows when using `convert_from_path` with multiple threads and was subsequently removed from PyPI.
fix
Do not use version 1.12.0. If you encounter this, upgrade to a later stable version (e.g., 1.12.1 or higher).
affects: 1.12.0
gotchaUsing outdated versions of Poppler can lead to `PDFPageCountError`, `Syntax Error`, or other unexpected issues when processing certain PDFs.
fix
Ensure your system's Poppler installation is up-to-date. Regularly check for and apply updates to Poppler utilities.
affects: All versions (when used with old Poppler)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pdf2image'
The `pdf2image` Python package is not installed in the currently active Python environment, or the Python interpreter being used by your IDE/script is not the one where the package was installed.
fix
Ensure you have the correct Python environment activated and install the package using `pip install pdf2image`. If using a virtual environment, activate it first.
FileNotFoundError: [Errno 2] No such file or directory: 'pdftoppm'
This error, or a similar one like `pdf2image.exceptions.PopplerNotInstalledError: Unable to get page count. Is poppler installed and in PATH?`, indicates that the underlying Poppler PDF rendering utilities (specifically `pdftoppm` or `pdfinfo`) are not installed on your system or are not accessible via your system's PATH environment variable. `pdf2image` is a wrapper and requires these external tools to function.
fix
Install Poppler utilities on your operating system. For Windows, download pre-compiled binaries and add the `bin/` folder to your system's PATH or explicitly pass `poppler_path` to `convert_from_path`. For macOS, use `brew install poppler`. For Debian/Ubuntu, use `sudo apt-get install poppler-utils`.
pdf2image.exceptions.PDFPageCountError: Unable to get page count.
This error often occurs when `pdf2image` cannot determine the number of pages in the PDF, usually due to a corrupted PDF file, a malformed PDF, or an outdated version of the Poppler utilities which might struggle with certain PDF formats (e.g., DocuSign PDFs or PDFs with syntax errors).
fix
First, ensure Poppler is up-to-date; if not, update it (e.g., `brew upgrade poppler` or reinstall `poppler-utils`). If the issue persists with a valid PDF, the file itself might be problematic. You can try opening it in a PDF viewer to confirm its integrity.
Upgrade
Version history
1.17.0latest on PyPI · released Jan 7, 2024
Audit
Dependencies
Poppler (pdftoppm, pdftocairo)requiredpdf2image is a wrapper around these command-line utilities and requires them to be installed and accessible in the system's PATH. Without Poppler, pdf2image cannot function.
Pillow (PIL Fork)requiredRequired for handling and manipulating the generated image objects.
Agent activity
55 hits · last 30 days
node
52
Amazon
1
Resources
pdf2image — pip install pdf2image · libregistry