datawhalechina/hello-agents · error · RuntimeError

pdfplumber is not installed. Install project dependencies be

Error message

pdfplumber is not installed. Install project dependencies before using PDF ingestion.

What it means

`_extract_pdf_payload` lazily imports pdfplumber and converts ModuleNotFoundError into RuntimeError('pdfplumber is not installed...') so the PDF-ingestion path fails with a clear message instead of a raw traceback. All PDF text/table extraction in the agent depends on this optional dependency.

Source

Thrown at Co-creation-projects/healer-666-Academic-Data-Agent/src/data_analysis_agent/document_ingestion.py:152

    df = pd.DataFrame(data_rows, columns=headers)
    stripped = df.astype(str).apply(lambda column: column.str.strip())
    if df.empty or (stripped == "").all().all():
        return None
    return df


def _extract_pdf_payload(
    pdf_path: Path,
    *,
    max_pdf_pages: int,
    max_candidate_tables: int,
    extracted_tables_dir: Path,
    persist_csv: bool = True,
) -> tuple[str, list[ExtractedTableRecord]]:
    try:
        import pdfplumber
    except ModuleNotFoundError as exc:  # pragma: no cover - depends on local environment
        raise RuntimeError(
            "pdfplumber is not installed. Install project dependencies before using PDF ingestion."
        ) from exc

    extracted_tables_dir.mkdir(parents=True, exist_ok=True)
    page_texts: list[str] = []
    records: list[ExtractedTableRecord] = []
    table_counter = 1

    with pdfplumber.open(pdf_path) as pdf:
        for page_index, page in enumerate(pdf.pages[: max(1, max_pdf_pages)], start=1):
            page_text = page.extract_text() or ""
            if page_text.strip():
                page_texts.append(page_text.strip())

            for raw_table in page.extract_tables() or []:
                if len(records) >= max(1, max_candidate_tables):
                    break
                df = _table_to_dataframe(raw_table)

View on GitHub (pinned to 606a07d341)

Solutions

1. Install it: `pip install pdfplumber` in the exact interpreter/venv the agent runs under.
2. Verify: `python -c "import pdfplumber; print(pdfplumber.__version__)"`.
3. Add pdfplumber to the project's dependency file so all environments get it.
4. If installation fails, check for pinned pdfminer.six conflicts (pdfplumber requires specific versions).

import importlib.util

def pdf_ingestion_ready() -> bool:
    return importlib.util.find_spec("pdfplumber") is not None

if not pdf_ingestion_ready():
    raise SystemExit("Install dependencies first: pip install pdfplumber")

try:
    result = ingest_document(pdf_path, data_dir, logs_dir)
except RuntimeError as e:
    if "pdfplumber is not installed" in str(e):
        subprocess.run([sys.executable, "-m", "pip", "install", "pdfplumber"], check=True)
        result = ingest_document(pdf_path, data_dir, logs_dir)
    else:
        raise

When it happens

Trigger: Running document ingestion (ingest_document or preview_pdf_tables) on a PDF in an environment where pdfplumber is not in site-packages — e.g. minimal install that skipped extras, or a venv recreated without reinstalling requirements.

Common situations: requirements.txt/pyproject optional-dependencies not installed (`pip install -e .` without the pdf extra), slim Docker images that trimmed packages, or dependency conflicts where pdfplumber was uninstalled by another package's installer.

Related errors

• 请安装 PyPDF2: pip install PyPDF2
• Miner Agent执行失败: {str(e)}
• 请安装 hello-agents: pip install 'hello-agents[all]>=0.2.7'
• 无法读取 PDF 文件：{e}
• Unsupported input file format: {source_path.suffix}

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/4803bc89ca362cea. Report an issue: GitHub.