ocrmypdf/OCRmyPDF · warning

Could not get CPU count. Assuming one (1) CPU. Use -j N to s

Error message

Could not get CPU count. Assuming one (1) CPU. Use -j N to set manually.

What it means

When multiprocessing.cpu_count() raises NotImplementedError (some sandboxes/container runtimes, CI restricted environments), available_cpu_count() warns and falls back to 1 CPU. Processing will be slow (single-threaded) unless -j/--jobs is set.

Source

Thrown at src/ocrmypdf/helpers.py:215

def monotonic(seq: Sequence) -> bool:
    """Does this sequence increase monotonically?"""
    return all(b > a for a, b in zip(seq, seq[1:], strict=False))


def page_number(input_file: os.PathLike) -> int:
    """Get one-based page number implied by filename (000002.pdf -> 2)."""
    return int(Path(input_file).name[0:6])


def available_cpu_count() -> int:
    """Returns number of CPUs in the system."""
    try:
        return multiprocessing.cpu_count()
    except NotImplementedError:
        pass
    warnings.warn(
        "Could not get CPU count. Assuming one (1) CPU. Use -j N to set manually."
    )
    return 1


def is_file_writable(test_file: StrOrBytesPath) -> bool:
    """Intentionally racy test if target is writable.

    We intend to write to the output file if and only if we succeed and
    can replace it atomically. Before doing the OCR work, make sure
    the location is writable.
    """
    try:
        p = Path(os.fsdecode(test_file))
        if p.is_symlink():
            p = p.resolve(strict=False)

        # p.is_file() throws an exception in some cases

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Pass -j N (CLI) or jobs=N (API) to set worker count explicitly
2. Upgrade the container/runtime so /proc/cpuinfo is available
3. If calling the helper directly, wrap it and default to os.process_cpu_count() (Python 3.13+) or a config value

Example fix

# before
ocrmypdf.ocr('in.pdf', 'out.pdf')
# after
ocrmypdf.ocr('in.pdf', 'out.pdf', jobs=4)

import os\njobs = os.process_cpu_count() if hasattr(os, 'process_cpu_count') else 4

When it happens

Trigger: Running OCRmyPDF (or calling available_cpu_count()) in environments where os.cpu_count()/multiprocessing.cpu_count() is unavailable — certain restricted containers, FreeBSD jails, or platforms lacking CPU affinity info.

Common situations: Docker with restricted /proc, minimal CI runners, some virtualized/sandboxed environments; user notices very slow OCR throughput.

AI-assisted analysis of ocrmypdf/OCRmyPDF@5074a0b0e1 (2026-08-27). Data as JSON: /api/errors/536d2abd9a082efa. Report an issue: GitHub.