@@ -1,11 +1,11 @@
 name: Build executables
 
 # Workflow 1 of 2: builds the three PyInstaller executables (Text2Pen, Update,
-# Installer) for Windows and Linux and uploads them as separate build
-# artifacts. It does not touch GitHub Releases — that's workflow 2, which will
-# take these artifacts and publish them as individual release assets, the
-# same way existing releases already do (so in-place updates via Update.exe
-# keep working).
+# Installer) for Windows and every supported Linux architecture, and uploads
+# them as separate build artifacts. It does not touch GitHub Releases —
+# that's workflow 2, which will take these artifacts and publish them as
+# individual release assets, the same way existing releases already do (so
+# in-place updates via Update.exe keep working).
 #
 # `workflow_call` is included so a future release workflow can trigger a
 # fresh build directly instead of reusing old artifacts.
@@ -32,13 +32,27 @@ jobs:
         include:
           - os: windows-latest
             label: windows
-          # Self-hosted (a Raspberry Pi) rather than a GitHub-hosted runner.
-          # NOTE: this makes the Linux build an ARM binary, not x86_64 — it
-          # will only run on ARM Linux (e.g. other Pis), not typical x86_64
-          # desktops. If both are needed, add back a GitHub-hosted
-          # `ubuntu-22.04` leg alongside this one.
-          - os: [self-hosted, Linux]
-            label: linux
+            hosted: github
+            pyinstaller: pyinstaller
+            add_data_sep: ";"
+            exe_suffix: ".exe"
+          # GitHub-hosted, so a fresh x86_64 VM every run: the common case,
+          # what almost every Linux desktop needs.
+          - os: ubuntu-22.04
+            label: linux-x86_64
+            hosted: github
+            pyinstaller: pyinstaller
+            add_data_sep: ":"
+            exe_suffix: ""
+          # Self-hosted (a Raspberry Pi) — the only realistic way to get an
+          # ARM64 build without cross-compiling. NOTE: this binary only runs
+          # on ARM64 Linux (other Pis, ARM SBCs), never on x86_64 desktops.
+          - os: [self-hosted, Linux, ARM64]
+            label: linux-arm64
+            hosted: self
+            pyinstaller: venv/bin/pyinstaller
+            add_data_sep: ":"
+            exe_suffix: ""
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
@@ -48,13 +62,26 @@ jobs:
       # runner is a persistent machine with its own system Python already
       # set up (see the apt note below), unlike an ephemeral GitHub-hosted VM.
       - uses: actions/setup-python@v5
-        if: matrix.label == 'windows'
+        if: matrix.hosted == 'github'
         with:
           python-version: "3.12"
 
-      # Deliberately no apt-get step for Linux here: the self-hosted runner
-      # is a persistent machine, so system packages only need installing
-      # once, by hand, not on every run:
+      # pywebview renders through WebKitGTK on Linux, and the portal
+      # screen-capture code (backend/portal_capture.py) needs GLib/D-Bus/
+      # GStreamer bindings. None of this is pip-installable; it has to come
+      # from apt, on the same interpreter pip installs into.
+      - name: Install Linux system dependencies
+        if: matrix.label == 'linux-x86_64'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            python3-gi gir1.2-webkit2-4.1 python3-tk \
+            gir1.2-gst-plugins-base-1.0 gstreamer1.0-plugins-base \
+            gstreamer1.0-plugins-good gstreamer1.0-pipewire \
+            python3-dbus libgirepository1.0-dev
+
+      # The self-hosted runner is persistent, not an ephemeral VM: install
+      # these once by hand instead, so every run doesn't re-apt-get them:
       #   sudo apt-get install -y python3-gi gir1.2-webkit2-4.1 python3-tk \
       #     gir1.2-gst-plugins-base-1.0 gstreamer1.0-plugins-base \
       #     gstreamer1.0-plugins-good gstreamer1.0-pipewire \
@@ -63,64 +90,49 @@ jobs:
       # (the last three are for pip to build python-uinput/pynput from
       # source on ARM, where prebuilt wheels are less common.)
 
-      - name: Install Python dependencies (Windows)
-        if: matrix.label == 'windows'
+      - name: Install Python dependencies (GitHub-hosted)
+        if: matrix.hosted == 'github'
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements.txt pyinstaller
 
-      # --system-site-packages: pywebview's WebKitGTK bindings and the
-      # portal-capture GLib/GStreamer bindings only exist as apt packages
-      # (see above), not on PyPI, so the venv needs to see the system ones.
-      - name: Install Python dependencies (Linux)
-        if: matrix.label == 'linux'
+      # --system-site-packages: the apt packages above (WebKitGTK/GStreamer
+      # bindings) only exist system-wide, not on PyPI, so the venv needs to
+      # see them. Recreated every run for a clean, reproducible build.
+      - name: Install Python dependencies (self-hosted)
+        if: matrix.hosted == 'self'
         run: |
           rm -rf venv
           python3 -m venv --system-site-packages venv
           venv/bin/pip install --upgrade pip
           venv/bin/pip install -r requirements.txt pyinstaller
 
-      - name: Build Text2Pen (Windows)
-        if: matrix.label == 'windows'
-        run: pyinstaller --onefile --noconsole --add-data "webui;webui" --name Text2Pen Text2Pen.py
-
-      - name: Build Text2Pen (Linux)
-        if: matrix.label == 'linux'
-        run: venv/bin/pyinstaller --onefile --noconsole --add-data "webui:webui" --name Text2Pen Text2Pen.py
-
-      - name: Build Update (Windows)
-        if: matrix.label == 'windows'
-        run: pyinstaller --onefile --noconsole --name Update Update.py
-
-      - name: Build Update (Linux)
-        if: matrix.label == 'linux'
-        run: venv/bin/pyinstaller --onefile --noconsole --name Update Update.py
+      - name: Build Text2Pen
+        run: ${{ matrix.pyinstaller }} --onefile --noconsole --add-data "webui${{ matrix.add_data_sep }}webui" --name Text2Pen Text2Pen.py
 
-      - name: Build Installer (Windows)
-        if: matrix.label == 'windows'
-        run: pyinstaller --onefile --noconsole --name Installer Installer.py
+      - name: Build Update
+        run: ${{ matrix.pyinstaller }} --onefile --noconsole --name Update Update.py
 
-      - name: Build Installer (Linux)
-        if: matrix.label == 'linux'
-        run: venv/bin/pyinstaller --onefile --noconsole --name Installer Installer.py
+      - name: Build Installer
+        run: ${{ matrix.pyinstaller }} --onefile --noconsole --name Installer Installer.py
 
       - name: Upload Text2Pen artifact
         uses: actions/upload-artifact@v4
         with:
           name: Text2Pen-${{ matrix.label }}${{ inputs.version != '' && format('-{0}', inputs.version) || '' }}
-          path: dist/Text2Pen${{ matrix.label == 'windows' && '.exe' || '' }}
+          path: dist/Text2Pen${{ matrix.exe_suffix }}
           if-no-files-found: error
 
       - name: Upload Update artifact
         uses: actions/upload-artifact@v4
         with:
           name: Update-${{ matrix.label }}${{ inputs.version != '' && format('-{0}', inputs.version) || '' }}
-          path: dist/Update${{ matrix.label == 'windows' && '.exe' || '' }}
+          path: dist/Update${{ matrix.exe_suffix }}
           if-no-files-found: error
 
       - name: Upload Installer artifact
         uses: actions/upload-artifact@v4
         with:
           name: Installer-${{ matrix.label }}${{ inputs.version != '' && format('-{0}', inputs.version) || '' }}
-          path: dist/Installer${{ matrix.label == 'windows' && '.exe' || '' }}
+          path: dist/Installer${{ matrix.exe_suffix }}
           if-no-files-found: error
@@ -1,5 +1,4 @@
 name: Create release
-#
 
 # Workflow 2 of 2: runs build.yml for a fresh set of executables, renames
 # them to their final release filenames, and publishes a new GitHub Release
@@ -62,32 +61,37 @@ jobs:
       # find, not a hardcoded nested path: upload-artifact's exact internal
       # layout for a single-file `path:` has shifted across versions, so this
       # locates each binary by name inside its artifact folder instead of
-      # assuming where under it it landed.
+      # assuming where under it it landed. The Linux binaries also get
+      # renamed here: inside the artifact they're just "Text2Pen" etc. (see
+      # build.yml), but a release holds x86_64 and arm64 side by side, so
+      # the uploaded asset name has to disambiguate — matches
+      # backend/paths.py's release_asset_name(), which is what Update.py and
+      # Installer.py use to pick the right one back up.
       - name: Lay out release assets with their final names
         run: |
           set -euo pipefail
           mkdir -p release
 
           copy_asset() {
             local artifact_dir="artifacts/$1"
-            local filename="$2"
+            local src_filename="$2"
+            local dest_filename="$3"
             local found
-            found=$(find "$artifact_dir" -type f -name "$filename" | head -n1)
+            found=$(find "$artifact_dir" -type f -name "$src_filename" | head -n1)
             if [ -z "$found" ]; then
-              echo "::error::Could not find $filename in $artifact_dir"
+              echo "::error::Could not find $src_filename in $artifact_dir"
               exit 1
             fi
-            cp "$found" "release/$filename"
+            cp "$found" "release/$dest_filename"
           }
 
-          copy_asset "Text2Pen-windows-${{ inputs.version }}"   "Text2Pen.exe"
-          copy_asset "Update-windows-${{ inputs.version }}"     "Update.exe"
-          copy_asset "Installer-windows-${{ inputs.version }}"  "Installer.exe"
-          copy_asset "Text2Pen-linux-${{ inputs.version }}"     "Text2Pen"
-          copy_asset "Update-linux-${{ inputs.version }}"       "Update"
-          copy_asset "Installer-linux-${{ inputs.version }}"    "Installer"
+          for name in Text2Pen Update Installer; do
+            copy_asset "$name-windows-${{ inputs.version }}"      "$name.exe" "$name.exe"
+            copy_asset "$name-linux-x86_64-${{ inputs.version }}" "$name"     "$name-linux-x86_64"
+            copy_asset "$name-linux-arm64-${{ inputs.version }}"  "$name"     "$name-linux-arm64"
+          done
 
-          chmod +x release/Text2Pen release/Update release/Installer
+          chmod +x release/*-linux-x86_64 release/*-linux-arm64
           ls -la release/
 
       - name: Create GitHub release
@@ -97,10 +101,4 @@ jobs:
           name: ${{ inputs.version }}
           body: ${{ inputs.release_notes }}
           prerelease: ${{ inputs.prerelease }}
-          files: |
-            release/Text2Pen.exe
-            release/Update.exe
-            release/Installer.exe
-            release/Text2Pen
-            release/Update
-            release/Installer
+          files: release/*
@@ -5,21 +5,26 @@
 
 import requests
 
-from backend.paths import APP_DATA_DIR, IS_LINUX, IS_WINDOWS, ensure_app_data_dir, exe_name
+from backend.paths import (APP_DATA_DIR, IS_LINUX, IS_WINDOWS, ensure_app_data_dir,
+                           exe_name, release_asset_name)
 
 if IS_WINDOWS:
     import win32com.client
 
 APP_NAME = "Text2Pen"
 
+# Local filenames — no CPU-architecture tag; that only matters for picking
+# the right download, below.
 INSTALL_DIR = APP_DATA_DIR
 EXE_NAME = exe_name("Text2Pen")
 UPDATE_NAME = exe_name("Update")
 EXE_PATH = os.path.join(INSTALL_DIR, EXE_NAME)
 UPDATE_PATH = os.path.join(INSTALL_DIR, UPDATE_NAME)
 
-DOWNLOAD_URL = f"https://github.com/pythonIsFast/Text2Pen/releases/latest/download/{EXE_NAME}"
-UPDATE_URL = f"https://github.com/pythonIsFast/Text2Pen/releases/latest/download/{UPDATE_NAME}"
+# Release asset names are architecture-specific on Linux (a release holds an
+# x86_64 and an arm64 binary side by side).
+DOWNLOAD_URL = f"https://github.com/pythonIsFast/Text2Pen/releases/latest/download/{release_asset_name('Text2Pen')}"
+UPDATE_URL = f"https://github.com/pythonIsFast/Text2Pen/releases/latest/download/{release_asset_name('Update')}"
 
 if IS_WINDOWS:
     STARTUP_DIR = os.path.join(
 
@@ -8,11 +8,12 @@
 import io
 import hashlib
 
-from backend.paths import APP_DATA_DIR, IS_LINUX, exe_name
+from backend.paths import APP_DATA_DIR, IS_LINUX, exe_name, release_asset_name
 
 APP_NAME = "Text2Pen"
 
-# Installation paths
+# Installation paths (local filenames — no CPU-architecture tag; that only
+# matters for picking the right download, below)
 INSTALL_DIR = APP_DATA_DIR
 TEXT2PEN_NAME = exe_name("Text2Pen")
 UPDATE_NAME = exe_name("Update")
@@ -22,9 +23,12 @@
 #Temp paths
 UPDATE_TEMP = UPDATE_PATH + "-newest"
 
-# URLs
-TEXT2PEN_URL = f"https://github.com/pythonIsFast/Text2Pen/releases/latest/download/{TEXT2PEN_NAME}"
-UPDATE_URL = f"https://github.com/pythonIsFast/Text2Pen/releases/latest/download/{UPDATE_NAME}"
+# Release asset names (architecture-specific on Linux — a release holds an
+# x86_64 and an arm64 binary side by side) and the URLs/hash keys built from them
+TEXT2PEN_ASSET = release_asset_name("Text2Pen")
+UPDATE_ASSET = release_asset_name("Update")
+TEXT2PEN_URL = f"https://github.com/pythonIsFast/Text2Pen/releases/latest/download/{TEXT2PEN_ASSET}"
+UPDATE_URL = f"https://github.com/pythonIsFast/Text2Pen/releases/latest/download/{UPDATE_ASSET}"
 
 class UpdateApp():
     def __init__(self, root):
@@ -50,7 +54,7 @@ def main(self):
             print("Checking GitHub release...")
             hashes = self.get_release_hashes()
 
-            github_hash = hashes[TEXT2PEN_NAME]
+            github_hash = hashes[TEXT2PEN_ASSET]
 
             if os.path.exists(TEXT2PEN_PATH):
                 local_hash = self.sha256_file(TEXT2PEN_PATH)
@@ -65,14 +69,14 @@ def main(self):
                     new_hash = self.sha256_bytes(new_data)
 
                     if new_hash != github_hash:
-                        raise ValueError(f"Downloaded {TEXT2PEN_NAME} failed SHA256 verification")
+                        raise ValueError(f"Downloaded {TEXT2PEN_ASSET} failed SHA256 verification")
             else:
                 self.status_label.config(text="Downloading Text2Pen...")
                 new_data = self.download_file_ram(TEXT2PEN_URL)
                 new_hash = self.sha256_bytes(new_data)
 
                 if new_hash != github_hash:
-                    raise ValueError(f"Downloaded {TEXT2PEN_NAME} failed SHA256 verification")
+                    raise ValueError(f"Downloaded {TEXT2PEN_ASSET} failed SHA256 verification")
 
             if os.path.exists(TEXT2PEN_PATH):
                 if new_data is not None:
@@ -85,7 +89,7 @@ def main(self):
                 self.write_file_once(temp_path, new_data)
                 self.replace_file(temp_path, TEXT2PEN_PATH)
 
-            github_updater_hash = hashes[UPDATE_NAME]
+            github_updater_hash = hashes[UPDATE_ASSET]
 
             if os.path.exists(UPDATE_PATH):
                 local_updater_hash = self.sha256_file(UPDATE_PATH)
@@ -99,21 +103,31 @@ def main(self):
                     new_updater_hash = self.sha256_bytes(updater_data)
 
                     if new_updater_hash != github_updater_hash:
-                        raise ValueError(f"Downloaded {UPDATE_NAME} failed SHA256 verification")
+                        raise ValueError(f"Downloaded {UPDATE_ASSET} failed SHA256 verification")
             else:
                 self.status_label.config(text="Downloading Updater...")
                 updater_data = self.download_file_ram(UPDATE_URL)
 
                 new_updater_hash = self.sha256_bytes(updater_data)
 
                 if new_updater_hash != github_updater_hash:
-                    raise ValueError(f"Downloaded {UPDATE_NAME} failed SHA256 verification")
+                    raise ValueError(f"Downloaded {UPDATE_ASSET} failed SHA256 verification")
 
             if os.path.exists(UPDATE_PATH):
                 if updater_data is not None:
                     self.write_file_once(UPDATE_TEMP, updater_data)
+                    # Windows locks a running .exe, so the swap has to wait
+                    # for Text2Pen.py's handoff logic on next launch. Linux
+                    # has no such lock — a process can replace its own
+                    # file while running — so finish the swap here directly;
+                    # otherwise Update would re-download "the newest" every
+                    # run forever without ever actually becoming current.
+                    if IS_LINUX:
+                        self.replace_file(UPDATE_TEMP, UPDATE_PATH)
             else:
                 self.write_file_once(UPDATE_TEMP, updater_data)
+                if IS_LINUX:
+                    self.replace_file(UPDATE_TEMP, UPDATE_PATH)
 
             self.status_label.config(text="Update finished!")
             self.progress_var.set(100)
 
@@ -36,13 +36,31 @@ def get_app_data_dir():
 
 
 def exe_name(base):
-    """`base` with the platform-appropriate executable suffix: Installer.py,
-    Update.py and Text2Pen.py all ship as "<name>.exe" on Windows and a
-    plain, extension-less "<name>" on Linux (matches the release asset
-    names uploaded by .github/workflows/build.yml)."""
+    """`base` with the platform-appropriate executable suffix, for the LOCAL
+    on-disk filename: Installer.py, Update.py and Text2Pen.py all install as
+    "<name>.exe" on Windows and a plain, extension-less "<name>" on Linux,
+    regardless of CPU architecture. For the GitHub release asset name (which
+    does vary by architecture, since one release holds every arch's binary
+    side by side), see release_asset_name()."""
     return f"{base}.exe" if IS_WINDOWS else base
 
 
+_LINUX_ARCH_TAGS = {"x86_64": "x86_64", "aarch64": "arm64", "arm64": "arm64"}
+
+
+def release_asset_name(base):
+    """`base`'s filename as uploaded to a GitHub Release. Matches the
+    `label` values in .github/workflows/build.yml's matrix, e.g.
+    "Text2Pen-linux-x86_64" or "Text2Pen-linux-arm64" — used to build
+    download URLs and to look up the right SHA256 from the release's asset
+    list (see Update.py, Installer.py)."""
+    if IS_WINDOWS:
+        return f"{base}.exe"
+    arch = platform.machine()
+    arch_tag = _LINUX_ARCH_TAGS.get(arch, arch)
+    return f"{base}-linux-{arch_tag}"
+
+
 APP_DATA_DIR = get_app_data_dir()
 
 LETTER_DB_FILE = os.path.join(APP_DATA_DIR, "letter_db.json")