Skip to content

The Installation Problems

Míng hàn edited this page Nov 7, 2026 · 2 revisions

NixOS

git-tree runs on NixOS, but not with the prebuilt binary from the Releases page. Build it from source with Nix instead; the repo ships a flake.nix and a shell.nix for this.


Quick start

With flakes (recommended)

Run without installing: nix run github:MahiroJV/git-tree

Install to your user profile: nix profile install github:MahiroJV/git-tree

Add to your NixOS / home-manager config (flakes)

In flake.nix: inputs.git-tree.url = "github:MahiroJV/git-tree";

In configuration.nix: environment.systemPackages = [ inputs.git-tree.packages.${pkgs.system}.default ];

Or in home.nix: home.packages = [ inputs.git-tree.packages.${pkgs.system}.default ];

Without flakes (classic Nix)

git clone https://github.com/MahiroJV/git-tree
cd git-tree
nix-shell
cargo run --release

The first build takes a few minutes because libgit2 and OpenSSL are compiled from source.

Development shell

nix develop      # flakes
nix-shell        # classic

Inside the shell, cargo run, cargo build --release and dx serve --platform desktop work as usual.


Troubleshooting

error while loading shared libraries: libxdo.so.3: cannot open shared object file

Cause: The prebuilt binary is built on Ubuntu, which ships libxdo.so.3. nixpkgs ships libxdo.so.4, so the binary can't find the version it was linked against.

Fix: Don't use the prebuilt binary. Use nix run github:MahiroJV/git-tree or nix-shell, as shown above. Building from source links against nixpkgs' own libxdo.so.4 automatically.

⚠️ Don't symlink libxdo.so.4 → libxdo.so.3 (for example in /tmp plus LD_LIBRARY_PATH). It may appear to work, but it's an unsupported hack and can break on any xdotool update.

Could not start dynamically linked executable / No such file or directory when running the binary

Cause: NixOS has no /lib64/ld-linux-x86-64.so.2, so generic Linux binaries can't start.

Fix: Build from source, as above. If you really need the prebuilt binary, the AppImage can be run with:

nix run nixpkgs#appimage-run -- ./git-tree-*-x86_64.AppImage

Window opens but is completely black or white

Cause: WebKitGTK's DMA-BUF renderer fails on many setups (NVIDIA, some Wayland compositors, VMs).

Fix: Recent versions set WEBKIT_DISABLE_DMABUF_RENDERER=1 automatically. If you're on an older version, or it's still black, try these one at a time:

WEBKIT_DISABLE_DMABUF_RENDERER=1 git-tree
WEBKIT_DISABLE_COMPOSITING_MODE=1 git-tree

Also make sure graphics drivers are enabled in your NixOS config:

hardware.graphics.enable = true;   # NixOS 24.11+
# hardware.opengl.enable = true;   # older releases

If none of this helps, please open an issue with your GPU (NVIDIA/AMD/Intel), driver, and whether you use Wayland or X11 (echo $XDG_SESSION_TYPE).

App crashes when clicking the 📁 folder picker (GLib-GIO-ERROR: No GSettings schemas are installed)

Cause: GTK can't find its settings schemas.

Fix: Use the provided flake.nix / shell.nix, which set these up. If you wrote your own shell, add:

export XDG_DATA_DIRS=${pkgs.gsettings-desktop-schemas}/share/gsettings-schemas/${pkgs.gsettings-desktop-schemas.name}:${pkgs.gtk3}/share/gsettings-schemas/${pkgs.gtk3.name}:$XDG_DATA_DIRS

error: path '/nix/store/...-source/flake.nix' does not exist (local clone)

Cause: Flakes only see files tracked by git.

Fix:

git add flake.nix flake.lock shell.nix

Build fails with Could not find openssl via pkg-config or Can't locate ... .pm (perl)

Cause: You're building outside the provided shell.

Fix: Run nix-shell or nix develop first. The vendored OpenSSL build needs perl and pkg-config, and both shells provide them.

Build fails with a missing .so or pkg-config package

Some nixpkgs revisions rename packages. Add the missing library to the runtimeLibs list in flake.nix / shell.nix and open an issue so it can be fixed for everyone.


Still stuck?

Open an issue and include:

  • The output of nixos-version
  • The command you ran and the full error
  • GPU, and Wayland or X11