git-cola: A Qt Git GUI That Runs From Its Source Tree

What git-cola solves, and who it is actually for

The README calls git-cola "a powerful Git GUI with a slick and intuitive user interface." That is the marketing line. The more useful description comes from the requirements: git 2.2.0 or newer, Python 3.9 or newer, and QtPy 2.0.0 or newer. This is a desktop client for people who already know git and want a window over it, not a replacement for the command line.

The audience is narrow and specific. Developers on Linux who want staging, diffing and rebase without typing every command. macOS users who want a native-feeling window, with the optional pyobjc package enabling macOS-specific application themes. Windows users, who are served by pynsist.cfg in the repository root and by the downloads page. The pyproject.toml classifiers list both "Developers" and "End Users/Desktop" as intended audiences, which matches the design: the same window has to work for someone doing an interactive rebase and for someone who just wants to see what changed.

What it does not try to be is a forge. There is no pull request view, no issue tracker, no hosted account. Everything it shows comes from the repository on disk.

How git-cola talks to git, and why that matters

git-cola is a Python application that uses QtPy as a compatibility layer over Qt. QtPy is the reason the project can ship one codebase against PyQt5, PyQt6 and PySide2. The README states that QtPy "defaults to pyqt5 and falls back to pyqt6 and pyside2 if pyqt5 is not installed", and that you can force the choice with the QT_API environment variable set to pyqt6, pyqt5 or pyside2. That single variable is the whole portability story for the GUI toolkit.

The repository layout confirms the shape of the project. The cola/ directory holds the application, qtpy/ is vendored alongside it, bin/ holds the launcher, share/ holds desktop files and icons, and docs/ holds the Sphinx sources including git-cola.rst and git-dag.rst. There is no compiled extension and no bundled git implementation. The git binary is a runtime requirement, which means the GUI inherits whatever git version and configuration you already have, including aliases, hooks and credential helpers. It also means a git upgrade can change behaviour under the GUI without git-cola changing at all.

The optional dependencies are worth reading closely because they are feature switches, not decoration. Send2Trash enables cross-platform "Send to Trash" functionality. notify2 enables desktop notifications. pyobjc enables macOS-specific application themes. websockets and msgpack, listed under extras in pyproject.toml, enable server/client functionality. Install git-cola without them and the application still runs; the corresponding menu items and behaviours simply are not there.

Installing git-cola on Ubuntu, Debian and other Linux distributions

The README is explicit that installation is optional: "Git Cola is designed to run directly from its source tree." The recommended path for the newest version is to install the Qt bindings from your distribution and then launch the script in bin/.

On a current Debian or Ubuntu system, one package covers the QtPy dependency:

sudo apt install python3-qtpy

On older releases where python3-qtpy is not available, the README lists the individual packages instead:

sudo apt install python3-pyqt5 python3-pyqt5.qtopengl python3-pyqt5.qtwebengine python3-pyqt5.qtsvg

If you prefer the Qt 6 stack, install the PyQt6 packages in place of the PyQt5 ones:

sudo apt install python3-pyqt6 python3-pyqt6.qtsvg python3-pyqt6.qtwebengine

After that, the README says you can launch ./bin/git-cola from the source tree "and there is nothing more to do." Most distributions also package the application directly. Debian and Ubuntu use apt install git-cola, Fedora uses dnf install git-cola, Gentoo uses emerge git-cola, and openSUSE and SLE use zypper install git-cola. Arch users are pointed at the AUR, Slackware at SlackBuilds.org, and FreeBSD at pkg install -r FreeBSD devel/git-cola. The distribution package will usually lag the latest release, which is the trade-off for not managing Python dependencies yourself.

A first real session with git cola and git dag

The PyPI route installs into a virtual environment. The README warns in bold that you should never run pip install or garden install outside of a virtualenv or as root, and that on Linux you should prefer the system package manager for PyQt.

python3 -m venv --system-site-packages env3
./env3/bin/pip install git-cola
./env3/bin/git-cola

The --system-site-packages flag matters here: it lets the virtualenv see the PyQt packages your distribution installed, so pip does not have to build a Qt binding. If you would rather track the source, the editable install is the documented way to upgrade with a plain git pull:

python3 -m venv --system-site-packages env3
./env3/bin/pip install --editable '.[extras,pyqt6]'
source env3/bin/activate
git cola

Once env3/bin is on your PATH, the README notes that git-cola installs itself as a git subcommand, so git cola and git dag work like built-in git commands. From a source checkout the same two commands are available as ./bin/git-cola and git dag, and the repository ships docs/git-dag.rst describing the DAG viewer. There is also a standalone install path for people who do not want a virtualenv: garden -D prefix=$HOME/.local install places the launcher at $HOME/.local/bin/git-cola, and the same recipe accepts DESTDIR for package staging.

Where git-cola stops being the right tool

The clearest limitation is the dependency chain. git-cola needs a working Qt binding. If you are on a headless server, in a container without an X or Wayland session, or on a distribution where PyQt5, PyQt6 and PySide2 are all unavailable, the application will not start. There is no terminal fallback and no web interface in the core package; the server/client functionality mentioned in pyproject.toml depends on the optional websockets and msgpack extras, and the README does not document what that mode does or how to configure it.

The second limitation is version skew. Because git-cola drives the git binary rather than linking a library, the GUI's behaviour is only as predictable as the git on your PATH. Requirements state git 2.2.0 or newer, which is a very low floor; nothing in the README says which newer git features the GUI surfaces or hides. If your team standardises on a recent git with new configuration, you are relying on git-cola having caught up.

The third is packaging lag. Distribution packages of git-cola are convenient but trail the releases. The project's own releases list shows v4.19.0 in July 2026 and v4.18.2 in March 2026, and a distro build may sit on either. If you need a specific fix, the source tree or the virtualenv install is the path, and the README says so directly.

git-cola versus GitHub Desktop, GitKraken and gitg

The honest comparison is about where the repository lives. GitHub Desktop and GitKraken are built around a hosted account. They assume a remote forge, they show pull requests and review state, and their workflows are organised around pushing branches to a service. git-cola has no account and no server component in its default configuration. It opens a local repository and shows you the index, the working tree, the history and the DAG. If your work is mostly reviewing other people's pull requests in a browser, git-cola is the wrong layer.

gitg is the closer comparison, since it is also a local GTK Git viewer. The difference in approach is the toolkit and the scope: git-cola is Python and Qt, cross-platform by way of QtPy, and ships a separate DAG viewer alongside the main window. gitg is a GNOME application. Choosing between them is largely choosing which desktop stack you already have installed.

Against the plain git command line, the trade-off is different again. git-cola does not abstract git away; it invokes it. That means your hooks, your aliases and your configuration still apply, which is an advantage over clients that reimplement Git's object model in a library. The cost is that anything the GUI does not expose still requires a terminal, and the README does not claim otherwise.

Licence, maintenance and the cost of upgrading

git-cola is licensed GPL-2.0, per both the repository metadata and the LICENSE file at the root. For most users this is irrelevant: running a GPL desktop application does not impose obligations on your own code. It matters if you intend to redistribute git-cola inside a product, bundle it into an appliance image, or link its modules into a proprietary application, because the GPL's terms then apply to that distribution. This is a description of the licence, not legal advice; read LICENSE and, if you are redistributing, talk to someone qualified.

The maintenance picture is straightforward. The repository is not archived, and the last push was on 2026-09-27. Releases are regular: v4.19.0 on 2026-07-12, v4.18.2 on 2026-03-16 and v4.18.1 on 2026-03-15. The project also carries an OpenSSF Best Practices badge and runs pre-commit.ci and GitHub Actions, all linked from the README, which suggests the release process is automated rather than manual.

Upgrade cost depends on how you installed it. A distribution package upgrades with the rest of your system and you get whatever version the distro ships. A virtualenv install upgrades with pip, and the editable install documented in the README upgrades with git pull. The source-tree approach means there is no upgrade step at all: you pull and rerun ./bin/git-cola. The Makefile exposes prefix and DESTDIR variables for staged installs, which is the path packagers use.

Editorial conclusion

Adopt git-cola if you want a desktop Git client whose dependencies are an ordinary git binary, Python 3.9 or newer and QtPy with PyQt5, PyQt6 or PySide2, and if you value being able to run it from a checkout without installing anything. Do not adopt it if you want a browser-hosted forge with pull requests and code review built in, or if you cannot install a Qt binding on the machine. Before committing, verify which Qt binding your distro provides, confirm the git version is 2.2.0 or newer, and check whether Send2Trash, notify2 or pyobjc are present, because each one switches on a feature that is otherwise silently missing.

Frequently asked questions

Official sources

1. git-cola/git-cola on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases