Update documentation to use pipx

[nazar-pc]

I just upgraded from Ubuntu 22.04 to 24.04 and expectedly Qtile didn't start anymore due to Python version change (3.10 -> 3.12). However, installation with pip did't work this time and I had to use pipx instead.

So instead of this:

pip install qtile

I had to do this:

sudo apt-get install pipx
pipx install qtile

And then to install additional layout (I think will be simialar for extras):

pipx inject qtile qtile-plasma

I'm not working with Python, so someone more knowledgable might want to update the documentation on how to do this correctly.

I suspect the same will work on older versions of Ubuntu and other distros, so pipx might as well be the default way going forward.

[tych0]

It didn't work because you have to reinstall for major python release upgrades (i.e. you only had the qtile module installed in $HOME/.local/lib/python3.10/site-packages/, but python3.12 doesn't look there). If you reinstall with pip3 on the new python version, it should work just fine. Similarly, i expect that pipx will break when you roll to 3.12.

[nazar-pc]

Right, I know why it broke on OS upgrade, this is not the first year I'm using Qtile, but this is the first time I was forced to use pipx instead.

[elParaguayo]

Why were you forced to use pipx? It's perfectly possible to install with pip.

I've never used pipx but my understanding is that it installs packages in a virtual environment and then exposes an executable to activate the environment and run the app. However, I don't think there's any magic there that means that pip no longer works.

If you're getting build errors with pip that you're not with pipx then I'd be interested in seeing those. I'll admit our build process is messy if you're trying to build with wayland support.

[nazar-pc]

On Ubuntu 24.04 I can not install Qtile with packaged pip into .local/lib anymore:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    
    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.
    
    See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

Yes, pipx will create a virtual environment per-package under .share/local/pipx.

[elParaguayo]

I think the concern with that was that packages installed to .local/lib could still cause issues as they're in the python sys.path value. So, if you had something like a package manager written in python, you could break this by installing packages into .local/lib which your package manager doesn't know about.

The solution is either to have your package manager handle installation or install in a virtual environment. For the latter, pipx helps but isn't mandatory. I suspect our docs could be clearer on this.

[nazar-pc]

I know Python ecosystem is not trivial, but as a regular non-Python developer if I run stock Ubuntu and pip install qtile results in an error, then I think improving docs (or changing the default to pipx since it seems to be objectively cleaner) is probably worth it.

[elParaguayo]

Agreed. One of the complaints we get about our docs is that they're aimed at more experienced users.

Would you be willing to submit a PR with some changes?

[nazar-pc]

I can try, but I don't feel very confident in whatever I'm suggesting here 😅

[tych0]

I personally just use --break-system-packages, but I expect that will not be appropriate for everyone :)

[elParaguayo]

I personally just use --break-system-packages, but I expect that will not be appropriate for everyone :)

That's because you know what you're doing!

[tych0]

Well, let's not go that far :)

My reasoning is: we have a relatively small set of dependencies, that are mostly unique to us: cffi, cairocffi, xcffib, and pywayland. We allow a relatively old version of cffi, so the system one probably satisfies pip and will not need to be updated. I have packages that depend on python3-cffi installed on my system.

For the rest of the hard dependencies, at least on my system, qtile is the only package that uses them. If users have a package installed from their package manager that depends on the system python3-xcffib that is too old, installing our newer one over the top will break things (i think? xcffib itself has a stable API, but there's some python packaging nonsense here that breaks). However, I don't have anything like this on my system, so it's fine to install these to my user's $PYTHONPATH.

I suppose there are other optional ones that we have, e.g. setproctitle or any of the libraries the various widgets use. If the system has an incompatible (meaning, API incompatible) one of those on it, things will break. Since we don't (and don't want to) specify these as hard dependencies, the solution is to build some API version detection code into qtile so it can use the old and new versions of those deps. But this hasn't been a problem as far as I know.

I suppose we could put all this in the docs, but it is a lot of mental load to keep in your head just to install the damn thing and play with it, I agree.

[nazar-pc]

Things were so much easier when Ubuntu/Debian shipped Qtile in their repos. Maybe someone wants to create a PPA?

[tych0]

Yeah, unfortunately our packager for debian ran out of time/interest.

[cr1ogen]

In Debian and derivatives, which do not have the qtile package in .deb, the only 2 ways to install them are to do an installation in a virtual python prefix or use the --break-system-packages command. In Debian I have been using the second alternative for months without any problem on my system

[AlexHarter]

I just installed qtile on a fresh Debian 12 install using pipx myself. Perhaps this method as well as the "--break-system-packages" could both be listed as options? It seems like pipx would be more in-line with Debian's emphasis on stability, so perhaps that could be the preferred one.

On a related note, I believe the Ubuntu/Debian section only gives instructions for X11 as the backend. If that is true, could we also add Wayland instructions for that section?

[tych0]

sure, can you send a patch with all of that?

[github-actions]

This issue is stale because it has been open 90 days with no activity. Remove the status: stale label or comment, or this will be closed in 30 days.