import gi fails: cannot import name '_gi' from partially initialized module 'gi'
ImportError: cannot import name '_gi' from partially initialized module 'gi' (most likely due to a circular import)Short answer
The message means Python started loading a module called gi and it could not finish. Either a file named gi.py (or a folder called gi) next to your script is being loaded instead of PyGObject, or the interpreter you use cannot see the system python3-gi package, as with a plain virtual environment.
Fix it fast
1Find out which cause you have
Ask Python which file it loads as gi and which interpreter you are running. A path inside your own project is the first cause; a path outside the system packages points to the second.
python3 -c "import sys; print(sys.executable)" python3 -c "import importlib.util as u; print(u.find_spec('gi'))"2Match what you see, then jump to its fix
- 1
find_spec('gi') prints a path inside your project, such as ./gi.py or ./gi/__init__.pyA file or folder called gi shadows the real packageFix - 2
which python3 shows a .venv path, and import gi worked outside the venvA virtual environment cannot see the apt-installed python3-giFix - 3
pip list shows PyGObject but the import still fails, or the pip build earlier printed errorsA pip-installed PyGObject is half built or conflicts with the system oneFix
- 1
What does the error look like?
ImportError: cannot import name '_gi' from partially initialized module 'gi' (most likely due to a circular import)
Cause 1 of 3
A file or folder called gi shadows the real package
1Check
The directory of the script you run is placed first on sys.path, ahead of installed packages, so a same-named file in it is loaded instead.
ls -d gi gi.py 2>/dev/null
find . -maxdepth 2 -name "gi*" -not -path "./.venv/*"2Fix
Rename your file or folder to something that does not clash, and remove the stale cache.
mv gi.py my_gtk_helpers.py
find . -name "__pycache__" -prune -exec rm -rf {} +3Verify
find_spec now points at the system package, and the import works.
python3 -c "import gi; print(gi.__file__)"Confirmed by docs.python.org
Cause 2 of 3
A virtual environment cannot see the apt-installed python3-gi
1Check
A virtual environment is isolated from the base Python's packages by default, so packages that belong to the base Python, such as one installed with apt, are not visible in it.
which python3
grep include-system-site-packages .venv/pyvenv.cfg2Fix
Create the environment with access to system packages, after installing the Ubuntu packages.
sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-4.0
python3 -m venv --system-site-packages .venv3Verify
Activate the new environment and import.
. .venv/bin/activate
python -c "import gi; print(gi.__file__)"Confirmed by docs.python.org
Cause 3 of 3
A pip-installed PyGObject is half built or conflicts with the system one
1Check
PyGObject from PyPI compiles against system libraries and needs build dependencies on Ubuntu.
python3 -m pip list 2>/dev/null | grep -iE "pygobject|pycairo"2Fix
Either remove the pip packages and use the apt route above, or install the documented build dependencies and rebuild Pycairo and PyGObject inside the environment.
sudo apt install libgirepository-2.0-dev gcc libcairo2-dev pkg-config python3-dev gir1.2-gtk-4.0
python3 -m pip install --force-reinstall pycairo PyGObject3Verify
The import works inside the environment.
python3 -c "import gi; print(gi.__file__)"Confirmed by pygobject.gnome.org
How do I stop it coming back?
- Never name your own module after a library you import (gi, random, json, test).
- For desktop apps on Ubuntu, prefer the apt python3-gi package and a venv made with --system-site-packages.
- Keep one way of installing PyGObject per project, not both apt and pip.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.imshow() works in one environment and fails in another
The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window.
2 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
You cannot pip install packages inside an Ubuntu Docker container
error: externally-managed-environment
If pip is missing, install the python3-pip package with apt, in the same RUN as apt-get update.
3 causes, each with a fix