Running pywebview on NixOS with a single shell.nix

How to run pywebview (Qt backend) on NixOS.

Why

pywebview's Qt backend uses prebuilt wheels (PyQt6 + QtWebEngine). On NixOS they can't find the shared libraries they expect, so the libraries have to be exposed through LD_LIBRARY_PATH.

The shell.nix below includes everything QtWebEngine/Chromium needs, so it works on a fresh NixOS install with nothing else installed.

shell.nix

{ pkgs ? import <nixpkgs> { } }:

let
  runtimeLibs = with pkgs; [
    # Base
    stdenv.cc.cc.lib
    zlib
    zstd
    brotli

    # GL / graphics
    libGL
    libglvnd # libEGL
    libgbm
    libdrm
    vulkan-loader

    # Wayland / input
    wayland
    libxkbcommon

    # X11
    libx11
    libxext
    libxrandr
    libxcomposite
    libxdamage
    libxfixes
    libxrender
    libxi
    libxcursor
    libxtst
    libxkbfile
    libxshmfence

    # xcb
    libxcb
    libxcb-util
    libxcb-cursor
    libxcb-wm
    libxcb-image
    libxcb-keysyms
    libxcb-render-util

    # GTK stack / fonts
    glib
    gtk3
    gdk-pixbuf
    pango
    cairo
    atk
    at-spi2-atk
    harfbuzz
    fontconfig
    freetype

    # QtWebEngine / Chromium
    dbus
    expat
    nss
    nspr
    cups
    alsa-lib
    libpulseaudio
    krb5
    icu
    libpng
    libjpeg
    libwebp
    libxml2
    libxslt
    lcms2
    libopus
    libevent
    minizip
    snappy
  ];
in
pkgs.mkShell {
  packages = [ pkgs.uv ];

  LD_LIBRARY_PATH = pkgs.lib.makeLibraryPath runtimeLibs;

  # --pure sets this to a nonexistent file, which breaks httpx
  SSL_CERT_FILE = "${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt";

  QTWEBENGINE_DISABLE_SANDBOX = "1";
  PYWEBVIEW_GUI = "qt";
}

What the non-obvious bits do:

• LD_LIBRARY_PATH: makes the libs above visible to the pip wheels
• SSL_CERT_FILE: only needed with nix-shell --pure, otherwise httpx breaks
• QTWEBENGINE_DISABLE_SANDBOX: the Chromium sandbox doesn't work here, so it's disabled
• PYWEBVIEW_GUI=qt: forces the Qt backend

Usage

nix-shell
uv init
uv add "pywebview[qt]"
uv run main.py

main.py

import webview

webview.create_window("Hello", "https://example.com")
webview.start()