how to create flatpak package of python project

1. 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/

1. 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')"

1. 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

1. 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

1. 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

1. 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