Building on Linux

On Linux, pyzed build makes a folder, dist/Shop/, with an executable called Shop and everything it needs. No signing is required.

Build it

1. Install uv if you do not have it:

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. In the project folder, build:

   uv

   uv run pyzed build

   pip

   source .venv/bin/activate
   pyzed build          # or: python -m pyzed build

3. Try it:

   ./dist/Shop/Shop

Which distribution to build on

The app links against the C library (glibc) of the system it was built on, and runs on that version or newer. Build on the oldest distribution you want to support. For example, an app built on Ubuntu 22.04 runs on Ubuntu 22.04, 24.04 and later, and on other distributions with glibc 2.35 or newer, but not on Ubuntu 20.04.

Building in a container

To build for older systems from a newer one, build inside a container of the older distribution (for example docker run -it -v "$PWD":/app -w /app ubuntu:22.04), install uv there and run uv run pyzed build.

Pyzed’s own wheels need glibc 2.28 or newer (manylinux_2_28), so that is the oldest base that can work. Alpine and other musl-based systems need a build made on them.

What the target needs

The app brings Python and Pyzed with it, but uses the system’s graphics and windowing libraries: a desktop session with X11 or Wayland, libxkbcommon, and a Vulkan or OpenGL driver (Mesa on most systems). Every desktop distribution has them; minimal server images may not.

Share it

As an archive

The simplest way: an archive of the folder. People unpack it anywhere and run ./Shop/Shop.

tar -czf Shop-linux-x86_64.tar.gz -C dist Shop
# or a zip, which the self-updater uses:
(cd dist && zip -qr ../Shop-linux-x86_64.zip Shop)

Name the zip <app>-linux-<arch>.zip if you plan to update the app by itself.

Add it to the application menu

A .desktop file makes the app appear in the desktop’s application menu, with its icon. Install it per user, no root needed:

~/.local/share/applications/com.acme.shop.desktop

[Desktop Entry]
Type=Application
Name=Shop
Exec=/home/you/.local/share/shop/Shop
Icon=/home/you/.local/share/shop/icon.png
Categories=Office;
Terminal=false

Pyzed Design’s Linux installer does exactly this: it downloads the release zip, checks it against the release’s SHA256SUMS, unpacks it into ~/.local/share/pyzed-design, links a command into ~/.local/bin and adds the menu entry. Its script, docs/public/install.sh, is a good template for your own curl ... | sh installer.

AppImage, .deb, .rpm, Flatpak, Snap

Not built by pyzed build yet

pyzed build makes the app folder only. Packaging it as an AppImage, a .deb/.rpm or a Flatpak/Snap is done with those formats’ own tools, starting from dist/Shop/:

• AppImage: put the folder in an AppDir with an AppRun that starts Shop, a .desktop file and an icon, then run appimagetool.
• .deb / .rpm: tools such as fpm turn a folder into either: fpm -s dir -t deb -n shop -v 1.0.0 dist/Shop/=/opt/shop/.
• Flatpak / Snap: write a manifest that copies the folder and declares the graphics and display permissions.

These recipes are not tested by Pyzed.

Things to know

• Architecture: the app is built for the machine it is built on: x86_64, or aarch64 on ARM (GitHub offers ARM runners too, see CI).
• No GPU: on virtual machines without a GPU, start the app with the CPU renderer if the window stays blank; see Troubleshooting.
• Executable bit: zip files made on Windows lose the executable bit. Build and archive Linux apps on Linux.