Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

import gi fails: cannot import name '_gi' from partially initialized module 'gi'

ErrorImportError: 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.

  • Applies to Ubuntu 24.04, Python 3.12, PyGObject from apt and from pip
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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'))"
  2. 2Match what you see, then jump to its fix

    1. 1find_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. 2which python3 shows a .venv path, and import gi worked outside the venvA virtual environment cannot see the apt-installed python3-giFix
    3. 3pip 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

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

Did this fix it?

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.cfg

2Fix

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 .venv

3Verify

Activate the new environment and import.

. .venv/bin/activate
python -c "import gi; print(gi.__file__)"

Confirmed by docs.python.org

Did this fix it?

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 PyGObject

3Verify

The import works inside the environment.

python3 -c "import gi; print(gi.__file__)"

Confirmed by pygobject.gnome.org

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.