jinja2 imports fine but jinja2.compiler is missing: the Python partial-install trap

There's a classic failure that shows up over and over in Python CLI bug trackers, and it's almost never a bug in the tool. Someone posted it recently in the aider repo. Windows 10, Python 3.10.9, no venv, plain system install. Every launch died instantly:

ModuleNotFoundError: No module named 'jinja2.compiler'

The traceback pointed through litellm -> arize -> jinja2.environment. And the odd part: import jinja2 worked fine. Only the compiler submodule was missing.

That's the tell. When a top-level package imports cleanly but one of its submodules is missing, the tool you're running is probably innocent. Your environment is broken. Two things cause this, and both take about two minutes to fix.

Cause 1: a partial install

pip was mid-write when something interrupted it. A dropped connection, a killed terminal, a power blip. Or an upgrade went sideways and left the package half-installed: the .dist-info metadata landed, some modules landed, but compiler.py never did. Python doesn't complain until something actually tries to import the file that isn't there.

Cause 2: shadowing

Python adds the directory you're running from to the front of the module search path. If there's a stray jinja2.py or a jinja2/ folder sitting in that folder, Python imports it instead of the real installed package. The imposter has no submodule, so the tool dies with a confusing error.

The issue thread even had a diagnosis comment naming exactly this. GitHub auto-minimized it as spam, which is its own kind of annoyance, but the content was right.

The fix, in order

1. See where the package actually resolves from

python -c "import jinja2; print(jinja2.__file__)"

If the path is your current working directory or anything outside site-packages, you've got shadowing. Run the tool from a different folder, or delete the stray file. Check for a folder too, both count.

2. Force a clean reinstall

pip skips packages it thinks are already installed. The flag that makes it reinstall anyway:

pip install --upgrade --force-reinstall jinja2

Then confirm the submodule imports now:

python -c "import jinja2.compiler"

If nothing prints and nothing raises, you're done.

3. Check for other broken deps while you're here

python -m pip check

This lists packages whose requirements aren't satisfied. If something else is half-broken, you want to know now, not after the next random crash.

4. The proper long-term fix: a venv

If you're running tools against a system Python that's been through years of installs and upgrades, this will bite again eventually. The clean move is to stop using system Python for this:

python -m venv venv
venv\Scripts\activate     # Windows
# Linux/macOS: source venv/bin/activate
pip install aider-chat

Everything lives in one folder, the mess of your system site-packages can't reach in, and if it ever breaks you delete the folder and start over. That's also what the folks in the issue thread recommended.

Caveats

• If reinstalling jinja2 doesn't fix it, reinstall the top-level app instead. That drags in a consistent set of deps and often repairs the whole mess.
• The original reporter never posted back which fix worked for them, so I can't say whether partial-install or shadowing was theirs. Both are cheap to test.
• This isn't jinja2-specific. Any "package imports fine but submodule is missing" error, pydantic or requests or whatever, has the same two causes and the same fix path.

The general lesson

Next time a Python CLI dies at startup with a ModuleNotFoundError for something you know is installed, don't go read the tool's source. Ask two questions: where is it resolving from, and is the install actually complete? One command answers the first, one flag fixes the second.

Original thread: https://github.com/Aider-AI/aider/issues/5653