Skip to content

Latest commit

 

History

History
92 lines (59 loc) · 2.15 KB

index.md

File metadata and controls

92 lines (59 loc) · 2.15 KB

You’ve just stepped on another Python rake — this time courtesy of Python 3.13, which broke your build not because your code is wrong, but because imghdr was removed from the standard library.

🧨 The Problem

The error:

ModuleNotFoundError: No module named 'imghdr'

comes from Sphinx trying to load the epub3 builder. Sphinx expects imghdr, which was removed in Python 3.13. The Jupyter Book stack (which still depends on Sphinx 5.x/6.x) is not ready for this yet.

✅ The Fix: Downgrade to Python 3.11 or 3.10

This is non-negotiable right now. The whole jupyter-book + sphinx ecosystem breaks on Python 3.13.

Here’s what to do:

🧱 Rebuild with Python 3.11 (or 3.10)

  1. Deactivate and remove the broken env:
deactivate
rm -rf myenv
  1. Use pyenv or Homebrew to install Python 3.11 if you don’t already have it:
brew install pyenv
pyenv install 3.11.8
pyenv local 3.11.8

Or, if using Homebrew directly:

brew install python@3.11
  1. Create a fresh env with 3.11:
python3.11 -m venv myenv
source myenv/bin/activate
pip install -r requirements.txt
  1. Test again:
cd list/kitabo/ensi
./python/deploy.py

🧠 Why this happened

  • imghdr was removed in Python 3.13 (PEP 594)
  • Sphinx still references it for EPUB3 generation.
  • Jupyter Book imports all Sphinx builders, even if you’re not building .epub, so you get punished for code you don’t even use.

This is peak Python ecosystem fragility — no layer separation, no fault tolerance.

🛡️ Bonus: Patch Around It (Temporary)

If downgrading is a hassle, you can monkeypatch your _config.yml to exclude EPUB3:

sphinx:
  config:
    epub_show_urls: 'footnote'
  builder: html

But this won’t fix it unless Jupyter Book itself stops loading the epub3 builder by default — which it doesn’t yet.

Verdict

Downgrade to Python 3.11 or 3.10. Lock it in your .tool-versions, pyproject.toml, or README. Don't touch Python 3.13 until Jupyter Book and Sphinx say they're ready — they're not.