`millet gui` fails with `ModuleNotFoundError: No module named 'gi'` in isolated venvs — PyGObject is undeclared and there is no `gui` extra

[lawa42]

Summary

millet gui depends on PyGObject at import time, but no millet package declares it and there is
no gui extra to opt into. The GUI therefore only works when the interpreter happens to see a
system-installed PyGObject. That assumption breaks for any isolated virtualenv install —
including the uv tool install / pipx flow that the README itself recommends — and it cannot
be worked around on distributions whose system PyGObject is built for a Python version millet
does not support.

Environment

• millet-pipeline 0.14.0, millet-record 0.5.0 (both current PyPI releases)
• Arch Linux
• Installed with:
  uv tool install millet-record --with "millet-pipeline[tee]" --python 3.11 --torch-backend cpu
• Tool venv: Python 3.11.15, include-system-site-packages = false
• System PyGObject: 3.56.3, built for system Python 3.14
• gtk3 1:3.24.52, gobject-introspection 1.86.0 present

Steps to reproduce

1. Install millet into an isolated venv (uv tool install or pipx install).
2. Run millet gui.

Actual behaviour

  File ".../site-packages/millet/cli/gui.py", line 116, in gui
    from millet.gui import launch
  File ".../site-packages/millet/gui.py", line 58, in <module>
    import gi
ModuleNotFoundError: No module named 'gi'

All other subcommands (record, transcribe, run, check, …) work fine; only gui is
affected.

Why this is not just a local packaging mistake

Two things make it unfixable from the user side on a current rolling-release distro:

1. Isolated venvs are the documented install path. uv tool and pipx both create venvs
   with include-system-site-packages = false. A system PyGObject is invisible by design.
2. Enabling system site-packages would not help here anyway. Arch's python-gobject is
   built only for the current system Python — 3.14 — while millet requires python <3.14
   (Requires-Python: <3.14,>=3.10). There is no interpreter on the machine that can see both
   millet and the distro PyGObject. The same applies to any distro that has moved to a Python
   newer than millet's cap.

REQUIREMENTS.md currently lists only the typelib side of the dependency
(sudo apt install gir1.2-gtk-3.0, "usually pre-installed"), which covers the GObject
introspection data but not the gi Python bindings inside the venv.

Suggested fix

Declare the Python-side dependency as an extra, e.g. in millet-pipeline:

[project.optional-dependencies]
gui = ["pygobject>=3.42", "pycairo>=1.20"]

so users can install with millet-pipeline[gui]. PyGObject and pycairo are sdist-only on PyPI
and build cleanly against the system glib2 / gobject-introspection / cairo development
files with meson + ninja — that worked without incident here.

Two things that would help regardless of whether the extra is added:

• Document it. A line in REQUIREMENTS.md / the GUI section noting that isolated-venv
  installs need PyGObject inside the venv, with the --with pygobject --with pycairo
  incantation for uv tool install, would save the next person the debugging.
• Fail with a useful message. Catching ImportError on import gi in millet/cli/gui.py
  and printing something like "the GUI needs PyGObject; install millet-pipeline[gui] or your
  distro's python-gobject" would be much friendlier than a bare traceback.

Workaround for anyone hitting this

uv tool install --force millet-record \
  --with "millet-pipeline[tee]" --with pygobject --with pycairo \
  --python 3.11 --torch-backend cpu

Note: on a system that also has GTK4 installed, this then surfaces a second, separate failure —
see #26 (unpinned Gdk import in millet/gui.py).

---

This issue was researched and written up with the help of Claude Opus 5.