Linux Packaging and Compatibility#

Upscayl is distributed on Linux through multiple package formats. Each has distinct sandboxing behavior that affects GPU/Vulkan access — the primary requirement for Upscayl's AI upscaling backend (upscayl-ncnn).

Package Formats#

Linux users can install Upscayl via 1:

Prerequisite: A Vulkan-compatible GPU is required. Most integrated GPUs (iGPUs) do not work, though they can be attempted 2.

Flatpak#

The Flatpak manifest is maintained in the repository at flatpak/org.upscayl.Upscayl.json. Key details:

• Runtime: org.freedesktop.Platform + org.electronjs.Electron2.BaseApp, both version 22.08 3
• GPU access: --device=dri grants the sandbox access to DRI/GPU devices 4
• Display: --socket=x11 only — Wayland is not exposed in the Flatpak finish-args 5
• Filesystem: --filesystem=home for reading/writing image files 6
• Sandbox wrapper: Uses zypak to wrap the Electron sandbox inside Flatpak 7
• Architecture: x86_64 only 8

The Flatpak is the recommended Linux package when GPU access or Vulkan issues are a concern, as it correctly provisions DRI access and avoids the AppArmor restrictions present in Snap.

Snap: AppArmor Blocks Vulkan Layer Access#

The Snap package configuration is not maintained in this repository — there is no snapcraft.yaml checked in 9. This is a key operational gap.

Known issue (Aug 2026): AppArmor confinement in the Snap package blocks read access to Vulkan layer directories, causing complete GPU detection failure 9:

profile="snap.upscayl.upscayl" name="/etc/vulkan/implicit_layer.d/" denied_mask="r"
profile="snap.upscayl.upscayl" name="/etc/vulkan/explicit_layer.d/" denied_mask="r"

• Effect: upscayl-bin (ncnn backend) cannot enumerate Vulkan devices → gpu.active: false
• Affected: AMD iGPU (Radeon 780M/GFX1103) on Ubuntu 22.04, Upscayl 2.15.0
• Unaffected: Flatpak and AppImage on the same system work correctly 9
• Fix location: Must be addressed at the Snap Store packaging level (snapcraft.yaml opengl plug or AppArmor profile), not in this repo. Can also be reported upstream to snapd 10

Workaround: Use Flatpak or AppImage instead of Snap.

Vulkan Driver Issues on Linux#

Upscayl's backend uses ncnn with Vulkan. Several Linux-specific Vulkan issues have been reported:

RADV Context Loss (vkQueueSubmit failed -4)#

Users on AMD RX 9070 XT (RADV GFX1201, Mesa 25.x, Arch Linux / Wayland) report total upscaling failure with 11:

radv/amdgpu: The CS has been cancelled because the context is lost.
vkQueueSubmit failed -4
WARNING: radv is not a conformant Vulkan implementation, testing use only.
lsfg-vk: something went wrong during lsfg-vk layer initialization: - unsupported configuration version

• Root cause: Mismatch between the RADV/Mesa Vulkan driver version and what ncnn expects; the lsfg-vk Vulkan layer (frame generation) has a version incompatibility with newer Mesa stacks 11
• Wayland-specific: At least one user confirms the crash only occurs on Wayland; switching to an X11 session resolves it 11
• AMDVLK note: Switching to AMDVLK was historically suggested but AMDVLK is now discontinued 11

Available workarounds:

• Run in an X11 session instead of Wayland
• Force a specific Vulkan ICD: VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/<icd>.json upscayl
• Set the GPU device ID explicitly in Upscayl's settings
• Process images one at a time (batch mode is more sensitive to driver instability) 11
• Downgrade Mesa to a previously working version

AMD iGPU Memory Allocation Failure (vkAllocateMemory failed -2)#

AMD integrated GPUs (Radeon 780M, 660M, 890M) can fail with vkAllocateMemory failed -2 due to an outdated ncnn dependency that cannot correctly select the GPU memory heap 12.

Workarounds:

• Replace upscayl-bin with the build from the ollm/upscayl-ncnn fork (updated ncnn) 12
• In BIOS, reduce iGPU dedicated memory allocation (e.g., from 4 GB to 2 GB or 1 GB) — counterintuitive but effective 12

Troubleshooting Entry Points#