What causes "compare_ocr_json.py requires `pip install shapely`" in PaddlePaddle/PaddleOCR?

pip install shapely in the same interpreter/environment that runs the script.

PaddlePaddle/PaddleOCR · error · RuntimeError

compare_ocr_json.py requires `pip install shapely`

Error message

compare_ocr_json.py requires `pip install shapely`

What it means

Raised lazily by compare_ocr_json.py the first time it needs to compute polygon IoU: the shapely geometry library is not importable. The script only imports shapely inside _polygon_iou, so the failure appears at comparison time rather than at startup, and it chains the original ImportError with an install hint.

Source

Thrown at deploy/ios_demo/scripts/compare_ocr_json.py:69

        prev = cur
    return prev[-1]


def _cer(ref: str, hyp: str) -> float:
    if not ref and not hyp:
        return 0.0
    if not ref:
        return 1.0
    return _levenshtein(ref, hyp) / max(len(ref), 1)


def _polygon_iou(
    poly_a: Sequence[Sequence[float]], poly_b: Sequence[Sequence[float]]
) -> float:
    try:
        from shapely.geometry import Polygon
    except ImportError as exc:
        raise RuntimeError(
            "compare_ocr_json.py requires `pip install shapely`"
        ) from exc

    def _to_poly(p: Sequence[Sequence[float]]) -> Polygon:
        pts = [(float(x), float(y)) for x, y in p]
        if len(pts) < 3:
            return Polygon()
        if pts[0] != pts[-1]:
            pts = pts + [pts[0]]
        return Polygon(pts)

    p1 = _to_poly(poly_a)
    p2 = _to_poly(poly_b)
    if p1.is_empty or p2.is_empty or not p1.is_valid or not p2.is_valid:
        return 0.0
    inter = p1.intersection(p2).area
    union = p1.union(p2).area
    if union <= 0:

View on GitHub (pinned to 2661c7c0ef)

Solutions

pip install shapely in the same interpreter/environment that runs the script.
If it should already be installed, verify with `python -c "import shapely; print(shapely.__version__)" using that exact interpreter.
Add shapely to the project's requirements file so CI picks it up.

Example fix

# before
RuntimeError: compare_ocr_json.py requires `pip install shapely`

# after
pip install shapely
python deploy/ios_demo/scripts/compare_ocr_json.py ref.json hyp.json

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util, sys

if importlib.util.find_spec("shapely") is None:
    sys.exit("shapely missing — run: pip install shapely")

# only now invoke the comparison
subprocess.run([sys.executable, "deploy/ios_demo/scripts/compare_ocr_json.py", ref, hyp])

Try / catch

try:
    from shapely.geometry import Polygon  # early, explicit import
except ImportError:
    Polygon = None  # or exit with install instructions

if Polygon is None:
    raise SystemExit("pip install shapely before running comparisons")

Prevention

Add shapely to requirements/dev-requirements for any repo containing compare_ocr_json.py.
Import heavy optional deps at startup, not lazily, so failures are immediate and obvious.
Pin the interpreter: run scripts with the same python that has the deps installed.

When it happens

Trigger: Running compare_ocr_json.py on a JSON pair whose items contain polygons (triggering _polygon_iou) in a Python environment where shapely is not installed or is broken.

Common situations: Fresh venv/CI image with only core PaddleOCR deps; shapely installed for a different interpreter than the one running the script; a corrupted shapely install that fails on import.

Related errors

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/c4b1d86048b31a3f. Report an issue: GitHub.