Create .deb package of python project

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 <[e-mail]>
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.