DEV Community

viraj-sh
viraj-sh

Posted on

How to create a flatpak of a python gui project

#linux #programming #python #tutorial

1. Install required tools and base flatpak packages 

apt install flatpak flatpak-builder pipx appstream unzip
Enter fullscreen mode Exit fullscreen mode

from flatpak we are going to install latest node extension and gnome (sdk & platform)

flatpak install org.freedesktop.Sdk.Extension.node26
flatpak install org.gnome.Sdk//51
flatpak install org.gnome.Platform//51
Enter fullscreen mode Exit fullscreen mode

pip and node generator

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

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/
Enter fullscreen mode Exit fullscreen mode

Verify python exists and version in gnome Sdk

flatpak run --command=python3 org.gnome.Sdk//51 --version
Enter fullscreen mode Exit fullscreen mode

2. Package Files

In packaging/flatpak dir in the root add .desktop, .xml, .svg, .yml files

io.github.viraj_sh.uniclare_client.desktop

[Desktop Entry]
Name=Uniclare Client
Exec=unidesk
Icon=io.github.viraj_sh.uniclare_client
Terminal=false
Type=Application
Categories=Utility;
StartupWMClass=unidesk
Enter fullscreen mode Exit fullscreen mode

io.github.viraj_sh.uniclare_client.metainfo.xml

<?xml version="1.0" encoding="UTF-8"?>
<component type="desktop-application">
  <id>io.github.viraj_sh.uniclare_client</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.uniclare_client.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>
Enter fullscreen mode Exit fullscreen mode

io.github.viraj_sh.uniclare_client.yml

id: io.github.viraj_sh.uniclare_client
runtime: org.gnome.Platform
runtime-version: '51'
sdk: org.gnome.Sdk
sdk-extensions:
  - org.freedesktop.Sdk.Extension.node26
command: unidesk

finish-args:
  - --share=network
  - --share=ipc
  - --socket=wayland
  - --socket=fallback-x11
  - --socket=system-bus
  - --device=dri
  - --env=PYWEBVIEW_GUI=gtk
  - --env=SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

modules:
  - python3-deps.json
  - python3-uv-build.json
  - name: uniclare-client
    buildsystem: simple
    build-options:
      append-path: /usr/lib/sdk/node26/bin
      strip: true
    build-commands:
      - 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
Enter fullscreen mode Exit fullscreen mode

Validate .xml file

appstreamcli validate --pedantic packaging/flatpak/io.github.viraj_sh.uniclare_client.metainfo.xml
Enter fullscreen mode Exit fullscreen mode

3. Dependences

Generate requirements.txt and remove pyqt or gnome related libraries since we are using flatpak gnome base package for the same

uv pip compile pyproject.toml --extra desktop -o requirements.txt
Enter fullscreen mode Exit fullscreen mode 
grep -viE '^(pyqt6|qtpy|pygobject|pycairo)' requirements.txt > requirements.clean.txt && mv requirements.clean.txt requirements.txt
Enter fullscreen mode Exit fullscreen mode

Run this to generate python3-deps.json

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

python3 flatpak-pip-generator.py \
  --runtime='org.gnome.Sdk//51' \
  --prefer-wheels=pydantic-core \
  --requirements-file=requirements.txt \
  --output ./packaging/flatpak/python3-deps
Enter fullscreen mode Exit fullscreen mode

Run this to generate python3-uv-build.json

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.gnome.Sdk//51' \
  --prefer-wheels=uv_build \
  --requirements-file=uvb.txt \
  --output ./packaging/flatpak/python3-uv-build
Enter fullscreen mode Exit fullscreen mode

Run this to generate generated-sources.json

flatpak-node-generator npm web/package-lock.json -o generated-sources.json
Enter fullscreen mode Exit fullscreen mode

4. Build & Test Locally

To build run this command

flatpak-builder --user --force-clean --install-deps-from=flathub --disable-rofiles-fuse build-dir ./packaging/flatpak/io.github.viraj_sh.uniclare_client.yml
Enter fullscreen mode Exit fullscreen mode

To install run this command

flatpak-builder --user --force-clean --install-deps-from=flathub --install --repo=repo build-dir ./packaging/flatpak/io.github.viraj_sh.uniclare_client.yml
Enter fullscreen mode Exit fullscreen mode

To RUN the app run this command

flatpak run io.github.viraj_sh.uniclare_client
Enter fullscreen mode Exit fullscreen mode

5. Create a Bundle

To create a bundle run this command

flatpak build-bundle ./packaging/flatpak/repo uniclare-client.flatpak io.github.viraj_sh.uniclare_client
Enter fullscreen mode Exit fullscreen mode

Check the bundle size

ls -lh ./packaging/flatpak/uniclare-client.flatpak
Enter fullscreen mode Exit fullscreen mode

Clean UP

To uninstall the app

flatpak uninstall --user -y io.github.viraj_sh.uniclare_client || true
Enter fullscreen mode Exit fullscreen mode

To cleanup flatpak packages

flatpak uninstall --user --unused -y || true
Enter fullscreen mode Exit fullscreen mode

Remove build dir and cache

rm -rf ./packaging/flatpak/build-dir ./packaging/flatpak/repo
Enter fullscreen mode Exit fullscreen mode

Remove apps persisted data

rm -rf ~/.var/app/io.github.viraj_sh.uniclare_client
Enter fullscreen mode Exit fullscreen mode

Remove flatpak builder cache

rm -rf .flatpak-builder
Enter fullscreen mode Exit fullscreen mode

Top comments (0)