DEV Community: viraj-sh

how to create flatpak package of python project

viraj-sh — Sun, 25 Oct 2026 11:16:23 +0000

Install required tools

apt install flatpak flatpak-builder pipx appstream

flatpak install flathub org.kde.Platform//6.11 org.kde.Sdk//6.11 com.riverbankcomputing.PyQt.BaseApp//6.11 org.freedesktop.Sdk.Extension.node24//25.08

download pip generator

wget https://raw.githubusercontent.com/flatpak/flatpak-builder-tools/master/pip/flatpak-pip-generator.py

download and install node generator

wget https://github.com/flatpak/flatpak-builder-tools/archive/refs/heads/master.zip
unzip master.zip "flatpak-builder-tools-master/node/*"
pipx install ./flatpak-builder-tools-master/node/

Verify Python and QWebEngineView

flatpak run --command=python3 org.kde.Sdk//6.11 --version

flatpak run --command=python3 com.riverbankcomputing.PyQt.BaseApp//6.11 -c "from PyQt6.QtWebEngineWidgets import QWebEngineView; print('PyQt6 WebEngine OK')"

Packaging files

make packaging/flatpak dir in the root add the following files

io.github.user_name.project_name.desktop

[Desktop Entry]
Name=Uniclare Client
Exec=unigui
Icon=io.github.viraj_sh.UniclareClient
Terminal=false
Type=Application
Categories=Utility;
StartupWMClass=unigui

io.github.user_name.project_name.metainfo.xml

<?xml version="1.0" encoding="UTF-8"?>
<component type="desktop-application">
  <id>io.github.viraj_sh.uniclareclient</id>
  <name>Uniclare Client</name>
  <summary>View data that is hidden on the Uniclare App or Student Portal</summary>
  <metadata_license>MIT</metadata_license>
  <project_license>MIT</project_license>
  <description>
    <p>Uniclare Client lets you view data that is hidden on the Uniclare App or Student Portal.</p>
  </description>
  <launchable type="desktop-id">io.github.viraj_sh.uniclareclient.desktop</launchable>
  <developer id="io.github.viraj_sh">
    <name>viraj-sh</name>
  </developer>
  <url type="homepage">https://github.com/viraj-sh/uniclare-client</url>
  <content_rating type="oars-1.1"/>
  <releases>
    <release version="3.0.0" date="2026-10-25"/>
  </releases>
</component>

io.github.user_name.project_name.svg or 512px png

then to verify the metinfo.xml run this command

sudo apt install appstream
appstreamcli validate --pedantic packaging/flatpak/io.github.viraj_sh.UniclareClient.metainfo.xml

Dependencies

now generate a requirements.txt and remove pyqt related packages do not remove qtpy its still needed remove pyqt related stuff

uv pip compile pyproject.toml --extra desktop -o requirements.txt

grep -viE '^(pyqt6|pyqt6-qt6|pyqt6-sip|pyqt6-webengine|pyqt6-webengine-qt6)' requirements.txt > requirements.clean.txt && mv requirements.clean.txt requirements.txt

then run this

export SSL_CERT_FILE=$(python3 -m certifi) # optional nixos

python3 flatpak-pip-generator.py \
  --runtime='org.kde.Sdk//6.11' \
  --prefer-wheels=pydantic-core \
  --requirements-file=requirements.txt \
  --output python3-deps

move this python3-deps.json into /packaging/flatpak/* dir

then generate the uv_build module (separate, because uv_build is a Rust/maturin sdist by default and must resolve to a manylinux wheel):

uv pip install pip
python -m pip download "uv_build>=0.11.21,<0.12.0" --only-binary=:all: --no-deps -d /tmp/uvb
ls /tmp/uvb   # confirm a .whl is present

echo "uv_build==0.11.33" > uvb.txt
python3 flatpak-pip-generator.py \
  --runtime='org.kde.Sdk//6.11' \
  --prefer-wheels=uv_build \
  --requirements-file=uvb.txt \
  --output python3-uv-build

open python3-uv-build.json and confirm the source URL ends with .whl (not .tar.gz). move python3-uv-build.json into /packaging/flatpak/.

then run this command

flatpak-node-generator npm web/package-lock.json -o generated-sources.json

move this generated-sources.json into /packaging/flatpak/*/ dir

now make a .yml file in /package/flatpak

id: io.github.viraj_sh.uniclare_client
runtime: org.kde.Platform
runtime-version: '6.11'
sdk: org.kde.Sdk
base: com.riverbankcomputing.PyQt.BaseApp
base-version: '6.11'
sdk-extensions:
  - org.freedesktop.Sdk.Extension.node24
command: unigui

cleanup-commands:
  - /app/cleanup-BaseApp.sh

finish-args:
  - --share=network
  - --share=ipc
  - --socket=wayland
  - --socket=fallback-x11
  - --device=dri
  - --env=PYWEBVIEW_GUI=qt

modules:
  - python3-deps.json
  - python3-uv-build.json
  - name: uniclare-client
    buildsystem: simple
    build-options:
      append-path: /usr/lib/sdk/node24/bin
    build-commands:
      - ls
      - cd web && npm ci --offline --cache=$FLATPAK_BUILDER_BUILDDIR/flatpak-node/npm-cache && npm run build
      - pip3 install --prefix=/app --no-deps --no-build-isolation .
      - install -Dm644 packaging/flatpak/io.github.viraj_sh.uniclare_client.desktop /app/share/applications/io.github.viraj_sh.uniclare_client.desktop
      - install -Dm644 packaging/flatpak/io.github.viraj_sh.uniclare_client.metainfo.xml /app/share/metainfo/io.github.viraj_sh.uniclare_client.metainfo.xml
      - install -Dm644 packaging/flatpak/io.github.viraj_sh.uniclare_client.svg /app/share/icons/hicolor/scalable/apps/io.github.viraj_sh.uniclare_client.svg
    sources:
      - type: dir
        path: ../..
      - generated-sources.json

then run this

flatpak-builder --user --force-clean --install-deps-from=flathub build-dir io.github.viraj_sh.uniclare_client.yml

Build & Test

install app locally

flatpak-builder --user --force-clean --install-deps-from=flathub --install --repo=repo build-dir io.github.viraj_sh.uniclare_client.yml

Run the app

flatpak run io.github.viraj_sh.uniclare_client

Running pywebview on NixOS with a single shell.nix

viraj-sh — Sun, 25 Oct 2026 08:04:52 +0000

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()

Develop and Publish Python Packages to PyPI

viraj-sh — Sat, 24 Oct 2026 22:20:49 +0000

Prerequisites

Pick a package name that isn't already taken on https://pypi.org/project/
Register an account on https://pypi.org/
Install uv and Python on your system

Steps

1. Initialize the project

Run this in the directory where you want the project:

uv init --package --name project_name --build-backend uv

This creates a src/project_name package and a pyproject.toml.

2. Write your code

Start coding inside ./src/project_name — that's where the package source lives. All your modules go here.

3. Update the project metadata

Edit pyproject.toml:

Update description
Add a license
Update the author name and email
Add your dependencies

Also update README.md and LICENSE.

4. (Optional) Add entry points for a CLI app or MCP server

If your app is a CLI or an MCP server, you can expose a command that gets installed on the user's system. Add an entry.py under the relevant subpackage.

CLI entry point — src/package_name/cli/entry.py:

# src/package_name/cli/entry.py
import sys


def run():
    try:
        from package_name.cli.main import cli
    except ModuleNotFoundError as e:
        if e.name in {"typer", "keyring"}:
            sys.exit(
                "Missing CLI deps. Install: uv tool install 'package_name[cli]'"
            )
        raise
    cli()

MCP server entry point — src/package_name/mcp_server/entry.py:

# src/package_name/mcp_server/entry.py
import sys


def run():
    try:
        from package_name.mcp_server.server import main
    except ModuleNotFoundError as e:
        if e.name == "fastmcp":
            sys.exit(
                "Missing MCP deps. Install: uv tool install 'package_name[mcp]'"
            )
        raise
    main()

Then register the commands in pyproject.toml:

[project.scripts]
command_name = "package_name.cli.entry:run"
mcp_server_name = "package_name.mcp_server.entry:run"

Note: the [cli] and [mcp] extras used above must be defined under [project.optional-dependencies] in pyproject.toml.

5. Update .gitignore and test locally

Add any files that should not be committed (virtual environments, dist/, secrets, etc.) to .gitignore, then test the application locally.

6. Build the package

uv build

This creates a .tar.gz (source distribution) and a .whl (wheel) in ./dist. Extract the .tar.gz and check its contents to make sure no unnecessary files are included.

7. Test the build locally

Before publishing, install the wheel to confirm it works.

As a library — install it into a virtual environment:

uv pip install ./dist/package_name-x.x.x-py3-none-any.whl

As a CLI or MCP server — uv tool install is meant for packages that expose a command (a CLI entry point or an MCP server entry point). Install the wheel with the relevant extra:

uv tool install "package_name[cli] @ ./dist/package_name-x.x.x-py3-none-any.whl"
# or
uv tool install "package_name[mcp] @ ./dist/package_name-x.x.x-py3-none-any.whl"

8. Publish to PyPI

Use the token to publish:

export UV_PUBLISH_TOKEN=pypi-...
uv publish

The package is now live under your account, and anyone can install it with:

pip install package_name

Note: a new token can be scoped to your whole account only until the project exists. After the first upload, create a token scoped to that project and use it for future releases.

9. Publish updates

After making code changes:

Bump the version in pyproject.toml:

uv version --bump patch   # or minor / major

Clean old builds:

rm -rf dist

Build:

uv build

Publish (with UV_PUBLISH_TOKEN set):

uv publish

You can also pass the token directly with uv publish --token pypi-....

Note: PyPI does not allow re-uploading a version that already exists, so always bump the version before publishing.