{"id":919,"library":"pdfplumber","title":"PDFPlumber","description":"PDFPlumber is a powerful Python library designed for high-precision extraction of text, tables, and detailed layout information from PDF documents. Built on `pdfminer.six`, it offers fine-grained control over PDF elements like characters, lines, rectangles, and curves, and includes robust visual debugging tools. The library is currently at version 0.11.9 and maintains an active development and release cadence with frequent updates to its core dependencies.","status":"active","version":"0.11.9","language":"python","source_language":"en","source_url":"https://github.com/jsvine/pdfplumber","tags":["PDF","data extraction","document processing","tables","text extraction","visual debugging"],"install":[{"cmd":"pip install pdfplumber","lang":"bash","label":"Install pdfplumber"},{"cmd":"sudo apt-get install poppler-utils # Debian/Ubuntu\r\nbrew install poppler # macOS","lang":"bash","label":"Install Poppler (for image features)"}],"dependencies":[{"reason":"Core parsing engine; pdfplumber is built on top of it.","package":"pdfminer.six","optional":false},{"reason":"Required for image-based features like `Page.to_image()` and visual debugging.","package":"Poppler","optional":true}],"imports":[{"symbol":"pdfplumber","correct":"import pdfplumber"},{"note":"While `import pdfplumber` is common, `from pdfplumber import open` is also used for direct access to the main entry point.","symbol":"open","correct":"from pdfplumber import open"}],"quickstart":{"code":"import pdfplumber\nimport os\n\n# Create a dummy PDF file for demonstration\n# In a real scenario, you'd replace 'dummy.pdf' with your actual file path.\n# This example just shows the API usage.\n\ntry:\n    # This part would typically involve a real PDF file\n    # For a runnable example, we'll assume 'dummy.pdf' exists or create a simple one (conceptually)\n    # For local testing, you might use a library like FPDF to generate a simple PDF\n    # or download a sample PDF.\n\n    # Placeholder: Replace with path to your actual PDF file\n    pdf_path = os.environ.get('PDFPLUMBER_DEMO_PDF', 'dummy.pdf')\n\n    # Example of how to use pdfplumber\n    with pdfplumber.open(pdf_path) as pdf:\n        print(f\"Number of pages: {len(pdf.pages)}\")\n        first_page = pdf.pages[0]\n        print(f\"Text from first page:\\n{first_page.extract_text()}\")\n\n        # Extract tables from the first page\n        tables = first_page.extract_tables()\n        if tables:\n            print(f\"\\nTables found on first page (first table):\\n{tables[0]}\")\n        else:\n            print(\"\\nNo tables found on the first page.\")\n\n        # Optional: Visual debugging (requires Poppler installed)\n        # im = first_page.to_image()\n        # im.draw_rects(first_page.chars)\n        # im.save(\"first_page_debug.png\")\n\nexcept FileNotFoundError:\n    print(f\"Error: PDF file '{pdf_path}' not found. Please provide a valid PDF for the quickstart.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to open a PDF, extract text from its first page, and find tables. For `to_image()` features and visual debugging, Poppler must be installed on your system. Remember to replace 'dummy.pdf' with the path to an actual PDF file."},"warnings":[{"fix":"Review code accessing `stroking_pattern` or `non_stroking_pattern` and adapt to new `pdfminer.six` object structures or alternative methods if needed. The `pdfminer.six` changelog may provide more context on the replacement functionality.","message":"In `v0.11.7`, `stroking_pattern` and `non_stroking_pattern` object attributes were removed due to underlying changes in `pdfminer.six`. Code relying on these attributes will break.","severity":"breaking","affected_versions":">=0.11.7"},{"fix":"Test existing extraction workflows with `v0.11.0` and later versions. If text extraction results differ, explicitly set `line_dir` and `char_dir` parameters in `extract_text()` or `pdfplumber.open()` to match the desired reading order.","message":"Version `v0.11.0` introduced new `line_dir` and `char_dir` parameters for better control over text directionality (e.g., non-left-to-right, top-to-bottom text). While enhancing support for complex PDFs, these changes might subtly alter text extraction behavior for certain documents if relying on previous implicit direction handling.","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"Always test `pdfplumber` upgrades thoroughly, especially if an underlying `pdfminer.six` version jump is noted in the release notes. Consult both `pdfplumber` and `pdfminer.six` changelogs for details on breaking changes.","message":"`pdfplumber` is built on `pdfminer.six`, and updates to `pdfminer.six` can sometimes introduce breaking changes or altered behavior in `pdfplumber`. `pdfplumber` often pins `pdfminer.six` versions, but large jumps can still have impacts.","severity":"gotcha","affected_versions":"All versions (during `pdfminer.six` upgrades)"},{"fix":"Always use `pdfplumber.open()` with a `with` statement (context manager) to ensure `PDF` and `Page` objects are properly closed and resources are released. If not using a `with` statement, explicitly call `pdf.close()` when done.","message":"When processing large PDF files or many documents, cached page and object properties can consume significant memory. Not properly closing PDF objects can lead to memory leaks.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install Poppler utilities specific to your operating system (e.g., `poppler-utils` on Debian/Ubuntu, `poppler` on macOS via Homebrew). See the installation instructions.","message":"Image-based features like `Page.to_image()` (used for visual debugging) require the Poppler utility library to be installed on your system. Without it, these methods will raise an error.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For users migrating from very old versions (<0.5.0), thoroughly review the table extraction documentation for `v0.5.0` and later. The `extract_tables()` method and its parameters were substantially changed.","message":"The table extraction algorithm in `pdfplumber` underwent a radical redesign in `v0.5.0`. This introduced significant breaking changes to the table extraction API and configuration, meaning code written for versions prior to `v0.5.0` will likely not work with newer versions.","severity":"breaking","affected_versions":"<0.5.0 to >=0.5.0"},{"fix":"Verify that your test environment or application context correctly provides all necessary PDF files. Check file paths, permissions, and ensure the files exist at the specified locations. If running tests, ensure test data is properly mounted or included in the test runner's environment.","message":"When running `pdfplumber` operations, ensure that all input PDF files specified in the code are present and accessible in the file system. If an input file is not found, a `FileNotFoundError` (or similar error indicating the file's absence) will be raised, preventing any PDF processing.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.11.9':54 'activ':58 'built':24 'cadenc':62 'charact':37 'control':32 'core':68 'current':51 'curv':41 'data':71 'debug':46,79 'depend':69 'design':8 'detail':18 'develop':59 'document':23,73 'element':35 'extract':13,72,77 'fine':30 'fine-grain':29 'frequent':64 'grain':31 'high':11 'high-precis':10 'includ':43 'inform':20 'layout':19 'librari':7,49 'like':36 'line':38 'maintain':56 'offer':28 'pdf':22,34,70 'pdfminer.six':26 'pdfplumber':1,2 'power':5 'precis':12 'process':74 'python':6 'rectangl':39 'releas':61 'robust':44 'tabl':16,75 'text':15,76 'tool':47 'updat':65 'version':53 'visual':45,78","created_at":"2026-03-29T06:07:41.970381+00:00","updated_at":"2026-04-16T17:57:02.466121+00:00","problems":[{"fix":"Ensure you are in the correct Python environment and run: `pip install pdfplumber`","cause":"The `pdfplumber` library has not been installed in the active Python environment or the Python interpreter being used does not have access to the installed package.","error":"ModuleNotFoundError: No module named 'pdfplumber'"},{"fix":"Rename any file named `pdfplumber.py` in your project directory to something else, then try re-importing. If the issue persists, reinstall `pdfplumber` using `pip uninstall pdfplumber` followed by `pip install pdfplumber`.","cause":"This usually occurs if you have named one of your Python files `pdfplumber.py` (creating a circular import) or if the `pdfplumber` package was not installed correctly.","error":"AttributeError: module 'pdfplumber' has no attribute 'open'"},{"fix":"It is often safe to upgrade `pdfminer.six` to a newer version compatible with other packages, or to reinstall `pdfplumber` which should pull the correct `pdfminer.six` version. Try `pip install pdfminer.six --upgrade` or `pip install pdfplumber --upgrade --no-deps` if you want to manage `pdfminer.six` separately, or uninstall both and reinstall `pdfplumber`: `pip uninstall pdfplumber pdfminer.six && pip install pdfplumber`.","cause":"`pdfplumber` has a strict dependency on a specific version of `pdfminer.six`, and another installed package (or a pre-existing installation) has a conflicting version of `pdfminer.six`.","error":"ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts. pdfplumber X requires pdfminer.six==YYYYMMDD, but you have pdfminer-six ZZZZ (which is incompatible)."},{"fix":"Add a check to ensure the result of `extract_text()` is not `None` before attempting string concatenation. For example: `text = page.extract_text(); if text: final_text += text`.","cause":"This error typically arises when `page.extract_text()` returns `None` (e.g., for an empty page, a page with only images, or a malformed page) and you attempt to concatenate this `None` value with a string.","error":"TypeError: can only concatenate str (not \"NoneType\") to str"},{"fix":"Install Poppler on your operating system. For Ubuntu/Debian: `sudo apt-get update && sudo apt-get install -y poppler-utils`. For macOS: `brew install poppler`. For Windows, you typically need to download pre-compiled binaries and add them to your system's PATH.","cause":"This error indicates that the `pdftotext` executable, which is part of the Poppler utility suite and is sometimes relied upon by `pdfplumber` or its underlying dependencies for certain operations (especially image-based PDF handling or specific text extraction methods), is not installed or not in your system's PATH.","error":"OSError: [Errno 2] No such file or directory: 'pdftotext'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.11.10","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/jsvine/pdfplumber","docs":null,"changelog":null,"pypi":"https://pypi.org/project/pdfplumber/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}