DEV Community: viraj-sh

Create .deb package of python project

viraj-sh — Fri, 06 Nov 2026 19:03:49 +0000

You're right—my previous answer assumed you already had an AppDir. Since you want to start completely from scratch, the most straightforward path is to reuse the exact same self-contained runtime construction logic from your AppImage tutorial, but instead of packaging the result into an AppImage, directly place that runtime directory into the .deb file structure.

The core idea is: build the Python environment first, then package it with dpkg-deb. Below are the complete steps.

Step 1: Install build tools and runtime dependencies

In Ubuntu, you need dpkg-deb (used to package .deb), uv (used to manage Python and build wheels), and some basic system libraries (for Qt/WebEngine runtime).

sudo apt update
sudo apt install -y dpkg-dev fakeroot curl patchelf file libgl1 libglib2.0-0 libfontconfig1 libx11-6 libxkbcommon0 libdbus-1-3

Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

Step 2: Prepare a self-contained Python runtime (completely from scratch)

This step replicates the runtime construction logic from your AppImage tutorial, but installs into a local directory instead of AppDir.

PKG="uniclare-client"
VER="3.0.0"
ARCH="amd64"
RUNTIME="runtime"   # 替代 AppDir，用来存放自包含运行时

rm -rf "$RUNTIME"
mkdir -p "$RUNTIME/usr/lib/unidesk"

Get the Python interpreter (using the Python 3.12 managed by uv):

PY_ROOT=$(dirname $(dirname $(readlink -f $(uv python find 3.12 --no-project))))
echo "PY_ROOT=$PY_ROOT"
test -x "$PY_ROOT/bin/python3" && echo "OK: interpreter exists"

# 复制解释器到运行时目录
cp -a "$PY_ROOT"/. "$RUNTIME/usr/lib/unidesk/python/"

Build the project wheel and dependency wheels (assuming you're at the project root and have pyproject.toml):

uv build --wheel
mkdir -p build/wheels

# 如果项目依赖中有 PyPI 上只有 sdist 的包（如 proxy-tools），按你原教程的方式构建 wheel
# uv build --wheel --out-dir build/wheels build/wheels/proxy_tools-0.1.0.tar.gz

# 导出锁定依赖（不含项目自身）
uv export --frozen --no-dev --no-emit-project --extra desktop --no-hashes -o build/requirements.txt

Install all Python dependencies into the runtime (using the just-copied interpreter, installing to site-packages):

uv pip install --python "$RUNTIME/usr/lib/unidesk/python/bin/python3" \
  --target "$RUNTIME/usr/lib/unidesk/site-packages" \
  --no-deps --no-build \
  --find-links build/wheels \
  -r build/requirements.txt dist/uniclare_client-3.0.0-py3-none-any.whl

Now runtime/usr/lib/unidesk/ contains the Python interpreter and all Python packages (including PyQt6 and WebEngine).

Step 3: (Strongly recommended) Prune the runtime

If you skip this step, the .deb will be very large (your AppImage tutorial mentions it can be reduced from 651M to around 400–450M). The pruning script from your original tutorial can be used directly, just change U=AppDir/... to U=runtime/usr/lib/unidesk/....

Create prune.sh (content based on your AppImage tutorial, replacing paths):

cat > prune.sh <<'PRUNE'
set -e
U=runtime/usr/lib/unidesk
PYLIB=$U/python/lib/python3.12
SP=$U/site-packages
QT=$SP/PyQt6/Qt6
QTLIB=$QT/lib

# A. 精简内置 Python
rm -rf $PYLIB/{test,idlelib,tkinter,turtledemo,lib2to3,ensurepip,pydoc_data}
rm -f  $PYLIB/turtle.py
rm -f  $PYLIB/lib-dynload/_tkinter*.so $PYLIB/lib-dynload/_test*.so \
       $PYLIB/lib-dynload/_ctypes_test*.so $PYLIB/lib-dynload/xxlimited*.so
rm -rf $PYLIB/site-packages/pip*
rm -rf $U/python/{include,share}
rm -rf $U/python/lib/{tcl*,tk*,itcl*,thread*}
rm -f  $U/python/lib/libtcl* $U/python/lib/libtk*
rm -f  $U/python/bin/{pip*,idle*,pydoc*,2to3*,python3.12-config}
find $U/python -name "*.a" -delete

# B. 通用 site-packages 清理
find $SP -type d -name tests -prune -exec rm -rf {} +
find $SP -name "*.pyi" -delete
rm -rf $SP/PyQt6/bindings $SP/PyQt6/uic/widget-plugins

# C. Qt 翻译（只保留 WebEngine en-US）
find $QT/translations -type f ! -path '*qtwebengine_locales/en-US.pak' -delete
find $QT/translations -type d -empty -delete
rm -f $QT/resources/qtwebengine_devtools_resources.pak
rm -rf $QT/qml $QT/bin

# D. Qt 插件裁剪
rm -rf $QT/plugins/{designer,sqldrivers,multimedia,qmltooling,sensors,position,geoservices,texttospeech,qmllint}

# E. 精简 PyQt6 绑定
KEEP=" QtCore QtGui QtWidgets QtNetwork QtWebChannel QtWebEngineCore QtWebEngineWidgets QtPrintSupport QtDBus QtOpenGL QtOpenGLWidgets QtSvg "
for f in $SP/PyQt6/*.abi3.so; do
  m=$(basename "$f"); m=${m%%.*}
  case "$KEEP" in *" $m "*) ;; *) rm -f "$f" "$SP/PyQt6/$m.pyi" ;; esac
done

# F. 依赖闭包删除无用 Qt C++ 库
declare -A need
queue=( $SP/PyQt6/*.abi3.so "$QT/libexec/QtWebEngineProcess" )
while IFS= read -r p; do queue+=("$p"); done < <(find "$QT/plugins" -name '*.so')
while ((${#queue[@]})); do
  f=${queue[0]}; queue=("${queue[@]:1}")
  for n in $(patchelf --print-needed "$f" 2>/dev/null | grep '^libQt6' || true); do
    b=${n%%.so*}
    [[ -n ${need[$b]:-} ]] && continue
    need[$b]=1
    [[ -e $QTLIB/$n ]] && queue+=("$QTLIB/$n")
  done
done
for f in $QTLIB/libQt6*; do
  b=$(basename "$f"); b=${b%%.so*}
  [[ -z ${need[$b]:-} ]] && rm -f "$f"
done

# G. 权限
find runtime -name "QtWebEngineProcess" -exec chmod +x {} \;
PRUNE

bash prune.sh

Step 4: Create the AppRun launcher (inside the runtime directory)

This is the entry point for the runtime; /usr/bin/uniclare-client will call it later.

cat > "$RUNTIME/AppRun" <<'EOF'
#!/bin/sh
HERE="$(dirname "$(readlink -f "$0")")"
U="$HERE/usr/lib/unidesk"
unset PYTHONHOME PYTHONSTARTUP
export PYTHONPATH="$U/site-packages"
export PYTHONNOUSERSITE=1 PYTHONDONTWRITEBYTECODE=1 PYTHONSAFEPATH=1
export LD_LIBRARY_PATH="$HERE/usr/lib:$HERE/usr/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH}"
export PYWEBVIEW_GUI=qt QT_API=pyqt6 QTWEBENGINE_DISABLE_SANDBOX=1
export QTWEBENGINEPROCESS_PATH="$U/site-packages/PyQt6/Qt6/libexec/QtWebEngineProcess"
export QTWEBENGINE_RESOURCES_PATH="$U/site-packages/PyQt6/Qt6/resources"
exec "$U/python/bin/python3" -m uniclare_client.interfaces.desktop "$@"
EOF
chmod +x "$RUNTIME/AppRun"

Test that the runtime starts properly (before packaging):

./runtime/AppRun

Step 5: Build the `.deb` directory structure

Now create the Debian package structure and move the runtime in.

PKG="uniclare-client"
VER="3.0.0"
ARCH="amd64"
APP_ID="io.github.viraj_sh.uniclare_client"

rm -rf deb-build
mkdir -p deb-build/$PKG/DEBIAN
mkdir -p deb-build/$PKG/opt/$PKG
mkdir -p deb-build/$PKG/usr/bin
mkdir -p deb-build/$PKG/usr/share/applications
mkdir -p deb-build/$PKG/usr/share/icons/hicolor/scalable/apps
mkdir -p deb-build/$PKG/usr/share/metainfo

# 把整个 runtime 放进 /opt/uniclare-client/
cp -a runtime/. deb-build/$PKG/opt/$PKG/

At this point, the runtime inside the .deb is located at /opt/uniclare-client/, and its AppRun is at /opt/uniclare-client/AppRun.

Step 6: Add desktop integration files

Use the .desktop, .svg, and .metainfo.xml from your project (paths based on your original tutorial):

install -Dm644 "packaging/appimage/$APP_ID.desktop" \
  "deb-build/$PKG/usr/share/applications/$APP_ID.desktop"
install -Dm644 "packaging/appimage/$APP_ID.svg" \
  "deb-build/$PKG/usr/share/icons/hicolor/scalable/apps/$APP_ID.svg"
install -Dm644 "packaging/appimage/$APP_ID.metainfo.xml" \
  "deb-build/$PKG/usr/share/metainfo/$APP_ID.metainfo.xml"

Modify the Exec line in the .desktop file to point to the Debian package's startup command:

sed -i 's|^Exec=.*|Exec=/usr/bin/uniclare-client|' \
  "deb-build/$PKG/usr/share/applications/$APP_ID.desktop"

Step 7: Create the `/usr/bin` launcher

cat > "deb-build/$PKG/usr/bin/uniclare-client" <<'EOF'
#!/bin/sh
exec /opt/uniclare-client/AppRun "$@"
EOF
chmod 755 "deb-build/$PKG/usr/bin/uniclare-client"

Step 8: Write the `DEBIAN/control` file

cat > "deb-build/$PKG/DEBIAN/control" <<EOF
Package: $PKG
Version: $VER
Section: utils
Priority: optional
Architecture: $ARCH
Maintainer: viraj-sh <viraj-sh@users.noreply.github.com>
Depends: libc6, libgl1, libglib2.0-0, libfontconfig1, libx11-6, libxkbcommon0, libdbus-1-3
Description: Uniclare Client
 View data that is hidden on the Uniclare App or Student Portal.
EOF

Note: You do not need to list python3 or python3-pyqt6 in Depends because you've bundled Python and PyQt6 yourself, so you don't rely on system packages. The listed system libraries are the basic dependencies needed for Qt/WebEngine to run, and they are present on virtually every Ubuntu desktop system.

Step 9: Set permissions and build

chmod 755 deb-build/$PKG/DEBIAN
chmod 644 deb-build/$PKG/DEBIAN/control
find deb-build/$PKG -type d -exec chmod 755 {} \;
chmod 755 deb-build/$PKG/usr/bin/uniclare-client

dpkg-deb --build --root-owner-group deb-build/$PKG "uniclare-client_${VER}_${ARCH}.deb"

Step 10: Install and test

sudo dpkg -i "uniclare-client_${VER}_${ARCH}.deb"
# 如果有依赖缺失：
sudo apt install -f

# 运行
uniclare-client

You should also be able to find and launch it from the application menu.

Uninstall:

sudo dpkg -r uniclare-client

Key differences from your original tutorial

Item	AppImage tutorial	This `.deb` procedure
Runtime location	`AppDir/`	`runtime/` (only a name change)
Runtime placement in package	`/` (AppImage root)	`/opt/uniclare-client/`
Entry point	`AppRun` executed directly	`AppRun` called via `/usr/bin/uniclare-client`
Packaging tool	`appimagetool`	`dpkg-deb`

The core "from scratch building Python + PyQt6 + WebEngine runtime" logic is completely identical to your AppImage tutorial; only the final packaging container is different. As long as ./runtime/AppRun can start the app normally, the .deb will also work normally.

Create App image of python desktop projects

viraj-sh — Fri, 06 Nov 2026 18:27:11 +0000

1. Install required tools

sudo apt update
sudo apt install git patchelf desktop-file-utils appstream file nodejs npm libfuse2t64 curl

wget https://github.com/linuxdeploy/linuxdeploy/releases/download/continuous/linuxdeploy-x86_64.AppImage

wget https://github.com/AppImage/appimagetool/releases/download/continuous/appimagetool-x86_64.AppImage

Make both appimages executable

chmod +x linuxdeploy-x86_64.AppImage appimagetool-x86_64.AppImage

2. Wheel

uv build --wheel

mkdir -p build/wheels
curl -L -o build/wheels/proxy_tools-0.1.0.tar.gz \
  https://pypi.org/packages/source/p/proxy-tools/proxy_tools-0.1.0.tar.gz

ls -l build/wheels/proxy_tools-0.1.0.tar.gz
file build/wheels/proxy_tools-0.1.0.tar.gz

proxy-tools has no wheel on PyPI; build one from sdist so --no-build later works

uv build --wheel --out-dir build/wheels build/wheels/proxy_tools-0.1.0.tar.gz

Verify static dir is present inside wheel

unzip -l dist/*.whl | grep static

Export Locked requirements

mkdir -p build
uv export --frozen --no-dev --no-emit-project --extra desktop --no-hashes -o build/requirements.txt

3. uild the bundled runtime

Assemble the AppDir Layout

APP_ID="io.github.viraj_sh.uniclare_client"

mkdir -p AppDir/usr/share/applications
mkdir -p AppDir/usr/share/icons/hicolor/scalable/apps
mkdir -p AppDir/usr/share/metainfo

Copy .desktop .metainfo.xml and .svg in the AppDir

# .desktop → root AND usr/share/applications/
cp "packaging/appimage/$APP_ID.desktop" "AppDir/$APP_ID.desktop"
cp "packaging/appimage/$APP_ID.desktop" "AppDir/usr/share/applications/$APP_ID.desktop"

# .svg → root AND usr/share/icons/hicolor/scalable/apps/
cp "packaging/appimage/$APP_ID.svg" "AppDir/$APP_ID.svg"
cp "packaging/appimage/$APP_ID.svg" "AppDir/usr/share/icons/hicolor/scalable/apps/$APP_ID.svg"

# metainfo → usr/share/metainfo/ only
cp "packaging/appimage/$APP_ID.metainfo.xml" "AppDir/usr/share/metainfo/$APP_ID.metainfo.xml"

Create AppRun

cat > AppDir/AppRun <<'EOF'
#!/bin/sh
HERE="$(dirname "$(readlink -f "$0")")"
U="$HERE/usr/lib/unidesk"
unset PYTHONHOME PYTHONSTARTUP
export PYTHONPATH="$U/site-packages"
export PYTHONNOUSERSITE=1 PYTHONDONTWRITEBYTECODE=1 PYTHONSAFEPATH=1
export LD_LIBRARY_PATH="$HERE/usr/lib:$HERE/usr/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH}"
export PYWEBVIEW_GUI=qt QT_API=pyqt6 QTWEBENGINE_DISABLE_SANDBOX=1
export QTWEBENGINEPROCESS_PATH="$U/site-packages/PyQt6/Qt6/libexec/QtWebEngineProcess"
export QTWEBENGINE_RESOURCES_PATH="$U/site-packages/PyQt6/Qt6/resources"
exec "$U/python/bin/python3" -m uniclare_client.interfaces.desktop "$@"
EOF

chmod +x AppDir/AppRun

Copy interpreter

PY_ROOT=$(dirname $(dirname $(readlink -f $(uv python find 3.12 --no-project))))
echo "PY_ROOT=$PY_ROOT"
test -x "$PY_ROOT/bin/python3" && echo "OK: interpreter exists"

mkdir -p AppDir/usr/lib/unidesk/python
cp -a "$PY_ROOT"/. AppDir/usr/lib/unidesk/python/

uv pip install --python AppDir/usr/lib/unidesk/python/bin/python3 \
  --target AppDir/usr/lib/unidesk/site-packages \
  --no-deps --no-build \
  --find-links build/wheels \
  -r build/requirements.txt dist/uniclare_client-3.0.0-py3-none-any.whl

4. Fix QtWebEngineProcess permissions (required, otherwise white screen)

find AppDir -name "QtWebEngineProcess" -exec chmod +x {} \;

5. Package AppImage

./appimagetool-x86_64.AppImage AppDir uniclare_client.AppImage

Steps 1-3 stay exactly as they are. Replace steps 4 and 5 with the ones below. Your du output shows the weight is in site-packages (540M, which is PyQt6 and the Chromium engine) and the bundled Python (111M, which carries tests, tcl/tk, static libs and pip).

One correction to my earlier script: it deleted the whole Qt6/translations folder, and that folder holds qtwebengine_locales. That could have caused the white screen again, so the version below keeps en-US.pak.

4. Prune the AppDir (new step, save as `prune.sh` and run `bash prune.sh`)

set -e
U=AppDir/usr/lib/unidesk
PYLIB=$U/python/lib/python3.12
SP=$U/site-packages
QT=$SP/PyQt6/Qt6
QTLIB=$QT/lib

############ A. Bundled Python ############
rm -rf $PYLIB/{test,idlelib,tkinter,turtledemo,lib2to3,ensurepip,pydoc_data}
rm -f  $PYLIB/turtle.py
rm -f  $PYLIB/lib-dynload/_tkinter*.so $PYLIB/lib-dynload/_test*.so \
       $PYLIB/lib-dynload/_ctypes_test*.so $PYLIB/lib-dynload/xxlimited*.so
rm -rf $PYLIB/site-packages/pip*
rm -rf $U/python/{include,share}
rm -rf $U/python/lib/{tcl*,tk*,itcl*,thread*}
rm -f  $U/python/lib/libtcl* $U/python/lib/libtk*
rm -f  $U/python/bin/{pip*,idle*,pydoc*,2to3*,python3.12-config}
find $U/python -name "*.a" -delete

############ B. Generic site-packages junk ############
find $SP -type d -name tests -prune -exec rm -rf {} +
find $SP -name "*.pyi" -delete
rm -rf $SP/PyQt6/bindings $SP/PyQt6/uic/widget-plugins

############ C. Qt: translations (keep only the WebEngine en-US locale) ############
find $QT/translations -type f ! -path '*qtwebengine_locales/en-US.pak' -delete
find $QT/translations -type d -empty -delete
rm -f $QT/resources/qtwebengine_devtools_resources.pak   # only needed for debug=True / remote devtools
rm -rf $QT/qml $QT/bin

############ D. Qt: plugins you don't need ############
rm -rf $QT/plugins/{designer,sqldrivers,multimedia,qmltooling,sensors,position,geoservices,texttospeech,qmllint}

############ E. Qt: remove unused Python bindings ############
KEEP=" QtCore QtGui QtWidgets QtNetwork QtWebChannel QtWebEngineCore QtWebEngineWidgets QtPrintSupport QtDBus QtOpenGL QtOpenGLWidgets QtSvg "
for f in $SP/PyQt6/*.abi3.so; do
  m=$(basename "$f"); m=${m%%.*}
  case "$KEEP" in *" $m "*) ;; *) rm -f "$f" "$SP/PyQt6/$m.pyi" ;; esac
done

############ F. Qt: delete C++ libs nothing depends on (dependency closure) ############
declare -A need
queue=( $SP/PyQt6/*.abi3.so "$QT/libexec/QtWebEngineProcess" )
while IFS= read -r p; do queue+=("$p"); done < <(find "$QT/plugins" -name '*.so')

while ((${#queue[@]})); do
  f=${queue[0]}; queue=("${queue[@]:1}")
  for n in $(patchelf --print-needed "$f" 2>/dev/null | grep '^libQt6' || true); do
    b=${n%%.so*}
    [[ -n ${need[$b]:-} ]] && continue
    need[$b]=1
    [[ -e $QTLIB/$n ]] && queue+=("$QTLIB/$n")
  done
done

for f in $QTLIB/libQt6*; do
  b=$(basename "$f"); b=${b%%.so*}
  [[ -z ${need[$b]:-} ]] && { echo "removing $b"; rm -f "$f"; }
done

############ G. Permissions (same as before) ############
find AppDir -name "QtWebEngineProcess" -exec chmod +x {} \;

du -sh AppDir

Test before packaging. If it fails, paste me the error output.

./AppDir/AppRun

5. Package with better compression

./appimagetool-x86_64.AppImage --comp zstd \
  --mksquashfs-opt -Xcompression-level --mksquashfs-opt 19 \
  --mksquashfs-opt -b --mksquashfs-opt 1M \
  AppDir uniclare_client.AppImage

If you want it even smaller and don't mind a slightly slower startup, use --comp xz and drop the zstd-specific options.

What to expect

The 651M AppDir should shrink to roughly 400-450M, and the AppImage to about 130-160 MB. Most of what remains is libQt6WebEngineCore and the Chromium resources, which you can't remove while using Qt WebEngine.

What I'd like to see next

To find any remaining big items specific to your app, paste the output of:

du -sh AppDir/usr/lib/unidesk/site-packages/* | sort -h | tail -15
du -sh AppDir/usr/lib/unidesk/site-packages/PyQt6/Qt6/* | sort -h | tail
uv python find 3.12 --no-project

The last command confirms the copied Python is a uv-managed standalone build and not the system Python. If it prints something under /usr, that alone would explain part of the 111M.

How to create a flatpak of a python gui project

viraj-sh — Thu, 29 Oct 2026 08:48:13 +0000

1. Install required tools and base flatpak packages

apt install flatpak flatpak-builder pipx appstream unzip

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

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/

Verify python exists and version in gnome Sdk

flatpak run --command=python3 org.gnome.Sdk//51 --version

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

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>

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

Validate .xml file

appstreamcli validate --pedantic packaging/flatpak/io.github.viraj_sh.uniclare_client.metainfo.xml

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

grep -viE '^(pyqt6|qtpy|pygobject|pycairo)' requirements.txt > requirements.clean.txt && mv requirements.clean.txt requirements.txt

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

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

Run this to generate generated-sources.json

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

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

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

To RUN the app run this command

flatpak run io.github.viraj_sh.uniclare_client

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

Check the bundle size

ls -lh ./packaging/flatpak/uniclare-client.flatpak

Clean UP

To uninstall the app

flatpak uninstall --user -y io.github.viraj_sh.uniclare_client || true

To cleanup flatpak packages

flatpak uninstall --user --unused -y || true

Remove build dir and cache

rm -rf ./packaging/flatpak/build-dir ./packaging/flatpak/repo

Remove apps persisted data

rm -rf ~/.var/app/io.github.viraj_sh.uniclare_client

Remove flatpak builder cache

rm -rf .flatpak-builder

this solved my error

viraj-sh — Thu, 29 Oct 2026 06:28:48 +0000

const call = async <T>(
  method: string,
  args: object = {},
): Promise<T> => {
  if (isDesktop()) {
    return viaBridge<T>(method, args);
  }

  await bridgeReady;

  if (isDesktop()) {
    return viaBridge<T>(method, args);
  }

  return viaHttp<T>(method, args);
};

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=unidesk
Icon=io.github.viraj_sh.uniclare_client
Terminal=false
Type=Application
Categories=Utility;
StartupWMClass=unidesk

io.github.user_name.project_name.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>

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 ./packaging/flatpak/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 ./packaging/flatpak/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: unidesk

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

finish-args:
  - --share=network
  - --share=ipc
  - --socket=wayland
  - --socket=fallback-x11
  - --socket=system-bus
  - --device=dri
  - --env=PYWEBVIEW_GUI=qt
  - --env=QTWEBENGINEPROCESS_PATH=/app/bin/QtWebEngineProcess
  - --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/node24/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

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

Clean everything for updating or testing

Remove the flatpak-builder state/cache directory, build directory and local repo

rm -rf .flatpak-builder
rm -rf build-dir repo

Remove the app's persisted data (localStorage, token, webview cache)

rm -rf ~/.var/app/io.github.viraj_sh.uniclare_client

Uninstall the currently installed flatpak app

flatpak uninstall --user -y io.github.viraj_sh.uniclare_client || true
flatpak uninstall --user --unused -y || true

Rebuild and test

Build

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

Install

flatpak install --user -y ./repo io.github.viraj_sh.uniclare_client

Run

flatpak run io.github.viraj_sh.uniclare_client

Create a bundle

Create the new bundle

flatpak build-bundle repo uniclare-client.flatpak io.github.viraj_sh.uniclare_client

Check bundle size

ls -lh uniclare-client.flatpak

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.