Codex PDF "No module named reportlab"? Use the Bundled Runtime

If a Codex PDF task fails on macOS with ModuleNotFoundError: No module named 'reportlab', do not assume Codex has no PDF support. First check which Python executable ran. A fresh upstream report shows that bare python3 can resolve to the user's PATH interpreter even while Codex's separate bundled runtime already contains reportlab, pdfplumber, and pypdf.

The safest temporary fix is to make Codex load its workspace dependency paths and run every PDF command with the returned Python executable. Do not guess an internal app path or globally rewrite PATH.

Confirm an Interpreter Mismatch

Run these read-only checks in the same Codex task that failed:

command -v python3
python3 -c 'import sys; print(sys.executable); print(sys.version)'
python3 -c 'import reportlab'

The first two commands identify the interpreter selected by the shell. The third reproduces the missing import without installing or changing anything.

This is an interpreter-specific result. It means the selected Python environment cannot import reportlab; it does not prove that every Python runtime available to Codex is missing the package. Python exposes the active interpreter path through sys.executable, which is the value to compare after Codex loads its bundled dependencies.

If the failure is instead that the dependency-loading command itself hangs, use the separate Codex workspace dependency diagnostic before changing packages.

Tell Codex to Use the Returned Python Path

Give Codex a bounded retry instruction:

Retry this PDF task with Codex's bundled workspace dependencies. First load the workspace dependency paths. Use the returned Python executable explicitly for every PDF command. Verify that reportlab, pdfplumber, and pypdf import successfully before generating the PDF. Do not guess an internal path, change my global PATH, or install packages unless the bundled dependency loader is unavailable.

After the dependency loader returns a path, keep that exact executable in a task-scoped variable:

BUNDLED_PYTHON="/absolute/path/returned/by/the/dependency/loader"
"$BUNDLED_PYTHON" -c 'import sys, reportlab, pdfplumber, pypdf; print(sys.executable); print("PDF runtime ready")'

Expected output includes the bundled interpreter path and PDF runtime ready. The path above is only an example because app and plugin installations can move. Re-resolve it for the current task instead of copying a path from another machine, app version, or session.

Then invoke the PDF generator with the same executable:

"$BUNDLED_PYTHON" scripts/render_report.py

Replace scripts/render_report.py with the reviewed generator in your workspace. Do not switch back to bare python3 for a later render or verification step, because that reintroduces the same ambiguity.

Why Changing Global PATH Is the Wrong Fix

Your shell Python may belong to Homebrew, pyenv, uv, Conda, a project virtual environment, or the macOS toolchain. Putting Codex's private runtime first in global PATH can silently change unrelated project commands and may break when the app updates.

Keep the two environments separate:

• use Codex's returned runtime path for the bundled PDF workflow;

• use the project's declared environment for repository code;

• use an explicit executable whenever the boundary matters; and

• resolve the path again after a Codex or plugin update.

This is the same reason an agent skill should declare and inspect its dependencies instead of assuming the user's shell owns them. If you install a third-party PDF skill or workflow, apply the agent skill audit checklist before letting it run package installers or file converters.

Use an Isolated Fallback Only When the Bundled Runtime Is Unavailable

If Codex cannot expose its bundled Python path and the PDF is urgent, create a project-local virtual environment only after confirming that external package installation is allowed:

python3 -m venv .venv-pdf
./.venv-pdf/bin/python -m pip install reportlab pdfplumber pypdf
./.venv-pdf/bin/python -c 'import reportlab, pdfplumber, pypdf; print("PDF environment ready")'

For repeatable work, pin reviewed versions in the repository's dependency file and use that source of truth. Do not use sudo pip, install into the system Python, or add an app-private runtime to a project lockfile.

This fallback changes the workspace and downloads packages, so it is not the first diagnostic step. Preserve the original error and interpreter path before installing anything; they are the useful evidence for the upstream report.

Verify the PDF, Not Just the Import

A successful import only proves that the libraries are available. Verify the generated artifact too:

1. Confirm the command exits successfully and writes the expected file.

2. Check that the file begins with a valid PDF signature.

3. Open it with pypdf using the same interpreter and confirm the expected page count.

4. Render every page to images and inspect them for clipped text, missing fonts, blank charts, overlaps, and broken links.

5. Re-run the generator once from a fresh Codex task to confirm that dependency resolution is repeatable.

For a three-page report, a compact structural check is:

"$BUNDLED_PYTHON" -c 'from pypdf import PdfReader; reader = PdfReader("output.pdf"); assert len(reader.pages) == 3; print("3 pages verified")'

Change the asserted count to the reviewed expectation. Do not treat a file that merely opens as proof that its visual content is correct.

Avoid These False Fixes

• Do not repeatedly install reportlab into whichever python3 happens to run.

• Do not copy a private runtime path from an issue report or another Mac.

• Do not globally prepend an app bundle to PATH.

• Do not delete project virtual environments before identifying the selected interpreter.

• Do not declare the issue resolved after imports pass; verify the rendered PDF.

The upstream issue was opened on August 6, 2026 against Codex CLI 0.146.1 on macOS. It reports PATH Python 3.14.5 failing the import while Codex's bundled Python 3.12.13 imports all three PDF libraries. That evidence supports the runtime-mismatch diagnosis for that configuration, not a claim that every PDF failure has the same cause.

Monitor the Upstream Fix With Aident Loadout

Aident Loadout can check the connected GitHub issue surface without placing a provider token in your prompt. Give Codex the canonical setup instruction:

Follow https://aident.ai/SETUP.md

Then use this bounded prompt:

Check my Aident Loadout account and Vault status. Find a connected read-only GitHub issue Action, inspect its current schema, and preflight it. Return the state, updated time, maintainer-authored comments, linked fixes, and release references for openai/codex issue 37333. Do not create or edit issues, post comments, change labels, change files, or ask me for a provider key.

Success is measurable: the result contains one current issue record, performs zero GitHub writes, and exposes no credential. Ready to track the fix safely? Set up Aident Loadout and run the read-only check.

Sources

• OpenAI Codex issue 37333: macOS PDF workflow uses PATH Python instead of bundled runtime

• OpenAI Codex issue 1797: PDF support

• Python documentation: sys.executable

• Python documentation: virtual environments

• ReportLab PDF Library User Guide

Refresh this guide when issue 37333 changes state, Codex exposes a stable documented runtime command, a release fixes interpreter selection, or the fresh-task verification no longer reproduces the mismatch.