beeware / beeware/toga

Linuxbrew causing issues with Toga installs

Open
#3,748 0 comments 0 reactions 0 assignees View on GitHub
awaiting details bug gtk linux
Dominant language
Python
Stars
5.4k
Forks
827
Avg merge
9h 45m
Merged PRs (30d)
58

Description

### Describe the bug

Initially reported as #3745.

It appears that having [Linuxbrew](https://docs.brew.sh/Homebrew-on-Linux) installed can cause issues with the operation of Toga.

### Steps to reproduce

1. On a Unix machine, install [Linuxbrew](https://docs.brew.sh/Homebrew-on-Linux)
2. Install GTK (or an app with GTK as a dependency) using Linuxbrew
3. Run toga-demo
4. See error
```
Traceback (most recent call last):
File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/gi/importer.py", line 139, in create_module
introspection_module = get_introspection_module(namespace)
File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/gi/module.py", line 243, in get_introspection_module
module = IntrospectionModule(namespace, version)
File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/gi/module.py", line 111, in __init__
repository.require(namespace, version)
~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
gi.RepositoryError: Typelib file for namespace 'cairo', version '1.0' not found

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
File "/tmp/toga-tutorial/./.venv/bin/toga-demo", line 7, in
sys.exit(run())
~~~^^
File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga_demo/__main__.py", line 6, in run
main().main_loop()
~~~~^^
File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga_demo/app.py", line 106, in main
return TogaDemo("Toga Demo", "org.beeware.toga-demo")
File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga/app.py", line 285, in __init__
self.factory = get_platform_factory()
~~~~~~~~~~~~~~~~~~~~^^
File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga/platform.py", line 120, in get_platform_factory
factory = importlib.import_module(f"{backend.value}.factory")
File "/home/linuxbrew/.linuxbrew/opt/python@3.13/lib/python3.13/importlib/__init__.py", line 88, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "", line 1387, in _gcd_import
File "", line 1360, in _find_and_load
File "", line 1331, in _find_and_load_unlocked
File "", line 935, in _load_unlocked
File "", line 1026, in exec_module
File "", line 488, in _call_with_frames_removed
File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga_gtk/factory.py", line 3, in
from . import dialogs
File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga_gtk/dialogs.py", line 5, in
from .libs import GTK_VERSION, Gtk
File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga_gtk/libs/__init__.py", line 2, in
from .gtk import * # noqa: F401, F403
^^^^^^^^^^^^^^^^^^
File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga_gtk/libs/gtk.py", line 10, in
from gi.repository import ( # noqa: E402, F401
...<7 lines>...
)
File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/gi/importer.py", line 141, in create_module
raise ImportError(e) from e
ImportError: Typelib file for namespace 'cairo', version '1.0' not found
```

### Expected behavior

Having installed GTK with Linuxbrew shouldn't prevent toga-demo (or any other Toga app) from starting.

### Screenshots

_No response_

### Environment

- Operating System: Fedora 42 (but likely any Linux)
- Python version: Any
- Software versions:
- Toga: 0.5.2

### Logs

```

```

### Additional context

There's a number of possible responses to this issue.

At the very least, we should document the potential conflict on the [Linux platform page](https://toga.readthedocs.io/en/stable/reference/platforms/linux.html) in the docs.

A more permanent fix will depend on what is possible with Linuxbrew.

It may be possible to Toga under Linuxbrew if the right Linuxbrew dependencies are installed. If this is the case, we should document those dependencies.

However, even if we can configure Linuxbrew appropriately, we also need to confirm that if a user builds a system package of their app with Briefcase, that package works:
1. If the developer has Linuxbrew installed but the end-user *doesn't*
2. If the developer *doesn't* have Linuxbrew installed, but the end user *does*.

If these two scenarios cause issues, it's not clear if that problem would represent a Toga issue or a Briefcase packaging issue.

Contributor guide

Open the contributing guide

Research direction

Start with the Linux platform page and reproduce the failure using Linuxbrew-installed GTK and toga-demo. Compare the documented Linux dependencies with the reported cairo typelib error, then determine whether the appropriate outcome is documentation, dependency guidance, or a Toga/Briefcase fix; done means the conflict and supported setup are clearly established.

Written by the indexing model from the issue text.

Assessment

Tech stack
linux, python
Domain
desktop, documentation, operating-systems
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.