Upscayl: a Vulkan-bound AI image upscaler for Linux, macOS and Windows

The problem Upscayl solves, and the hardware it assumes

Upscaling a small image used to mean either a blurry bicubic resize or a paid desktop tool. Upscayl takes the first path out of that choice: it runs Real-ESRGAN models locally, through ncnn's Vulkan backend, and presents the result in a desktop GUI. The README describes the goal as enlarging and enhancing low-resolution images, and the FAQ explains the mechanism bluntly: the models enhance an image by guessing what the details could be.

The audience is narrower than the download page suggests. The installation notes carry an explicit warning that a Vulkan compatible GPU is required, and that many integrated GPUs do not work. The FAQ repeats it: Upscayl will not work with most iGPUs or CPUs. A linked GitHub issue, #390, holds a community workaround for Windows and Linux, and the FAQ notes that no equivalent exists for macOS or Haiku. If you are on a laptop with Intel integrated graphics and no discrete GPU, the honest answer is that this is probably not your tool, though the README says there is no harm in trying.

The second constraint is content type. Upscayl enhances images that are low resolution or pixelated. It cannot de-blur or adjust focus. A photograph that is out of focus, or blurred by motion, will come back larger and still out of focus. The README points readers at the before/after examples in COMPARISONS.MD and suggests matching your input to those.

How the Electron front end talks to the ncnn backend

The repository splits cleanly into a renderer and an Electron main process. package.json declares "main": "export/electron/index.js", so the compiled Electron entry point lives under export/, while the UI is a Next.js app under renderer/. Top-level directories include electron/, renderer/, common/, models/, apis/, scripts/ and build/. The start script is `tsc && electron .`: TypeScript is compiled first, then Electron launches against the compiled output.

The actual upscaling does not happen in JavaScript. The FAQ states that Upscayl uses Real-ESRGAN and Vulkan architecture, and that the backend is a separate project, upscayl-ncnn, released under AGPLv3. That separation matters for anyone auditing the tool: the GUI is a front end, and the model inference runs in a native binary. The repository contains an update_upscayl_ncnn_binaries.sh script at the top level, which implies the native binaries are pulled in rather than built from the app's own source tree.

Models are a first-class concept here. There is a models/ directory, a separate upscayl/custom-models repository linked from the README for additional models, and a wiki page titled Model Conversion for creating your own. The README also documents a batch behaviour worth knowing before you file a bug: when a model does not support an action, Upscayl finishes upscaling every image in the batch before running post-processing. If you stop a batch midway, your images may be unprocessed, uncompressed, or at the wrong scale. The documented fix is to wait.

Installing Upscayl on Linux, macOS and Windows

Every platform starts at the same place: the releases page or upscayl.org. On Linux, the README lists Flatpak, AppImage, AUR, Snap and Gentoo ebuilds, and notes that most distributions carry Upscayl in their software listings. The portable route is the AppImage, which needs its execute permission set before it will run:

chmod +x upscayl-x.x.x-linux.AppImage
./upscayl-x.x.x-linux.AppImage

If you right-click the file in a graphical file manager instead, the README says to open the Permissions tab, check allow file to execute, and double click. RPM, DEB and ZIP builds are also published for Fedora, Debian/Ubuntu and generic x86 Linux.

On macOS 12 and later, the README gives a dmg flow: download upscayl-x.x.x-mac.dmg, drag the icon into Applications, then right-click the app in Applications and choose Open twice to get past Gatekeeper. Homebrew users have a one-line alternative:

brew install --cask upscayl

The Mac App Store listing is also linked. On Windows 10 and later, download upscayl-x.x.x-win.exe and run it. The README warns about SmartScreen: click More Info, then Run Anyway, or accept the unverified publisher dialog. None of these steps install a GPU driver, and that is the part most likely to decide whether the app launches into a working state.

For a first real use, open the app, pick an image, select a model, choose an output folder, and press the upscale button. The README's own tutorial material lives at docs.upscayl.org, and the before/after comparisons in COMPARISONS.MD show what a realistic result looks like on the kind of input the project considers in scope.

Building Upscayl from source, and what the scripts do not cover

The development section recommends Volta for managing Node.js. After installing Volta, the documented command is `volta install node`. From there, the README gives a clone, install, run sequence:

git clone https://github.com/upscayl/upscayl
cd upscayl
npm install
npm run start

The README notes that logs appear in the terminal during development, and that you can skip git entirely by downloading the source zip and extracting it to a folder named upscayl. Packaging uses `npm run dist`, and publishing uses `npm run publish-app` with a GH_TOKEN in the shell, which the README marks as maintainer-only. Per-platform scripts exist for AppImage, Flatpak, deb, rpm, zip and a universal macOS zip.

The gap is in the native side. The README does not document how to build upscayl-ncnn from source, how the binaries in the repository are produced, or what update_upscayl_ncnn_binaries.sh expects to find. Anyone forking Upscayl to change inference behaviour, rather than UI behaviour, will be working outside the documented path. The README also does not document rollback for a failed upgrade or a downgrade to a previous release.

Where Upscayl is the wrong tool

The clearest failure mode is documented by the project itself. Blurred or out-of-focus images do not improve. The FAQ says Upscayl cannot de-blur or do focus adjustment, and directs users to different tools for that job. If your problem is camera shake, missed autofocus, or heavy compression artefacts that read as blur, upscaling will enlarge the problem along with the image.

The second limit is hardware. NCNN Vulkan needs a Vulkan-compatible GPU. Integrated graphics frequently fail, and the FAQ states the app will not work with most iGPUs or CPUs. A workaround exists for Windows and Linux in issue #390, but it is community-contributed and the FAQ says nobody knows how to manipulate the macOS and Haiku frameworks. On a Mac without a suitable GPU, there is no documented fallback.

The third limit is operational. Batch upscaling is not interruptible in the way a file copy is. Because post-processing runs after all images are upscaled, stopping the batch leaves you with a mixed set of outputs. There is also no CLI in this repository: the FAQ points to upscayl-ncnn as the CLI tool. If your workflow is a shell script over ten thousand images on a headless server, the desktop app is the wrong entry point, and the backend project is the one you want.

Finally, the project's own maintenance signal is worth stating plainly. The last push to the repository was on 2024-12-25, the same day as the v2.15.0 release. That is not an archived project, but it is not a repository with recent activity either, and the README's roadmap entry, fix bugs, is the only forward-looking statement it makes.

How Upscayl differs from Topaz Gigapixel and from command-line upscalers

The keyword list in package.json names Topaz Gigapixel directly, which tells you the comparison the project expects. The difference is licensing and distribution, not necessarily output quality. Gigapixel is a commercial product; Upscayl is AGPL-3.0 and free to download, and its backend is separately open source under the same licence. If your constraint is budget or the ability to read the inference code, that difference decides the choice on its own.

The more interesting alternative is upscayl-ncnn, the project's own CLI. Same models, same Vulkan backend, no Electron window. For batch work on a machine you reach over SSH, the CLI is the appropriate layer, and the FAQ names it as the CLI tool rather than pointing at anything in this repository. The trade-off is that you lose the model picker, the output folder selection and the visual before/after, all of which the GUI provides.

A third option is any cloud upscaling service, including Upscayl's own hosted offering. The distinction is where your images go. Upscayl runs inference locally, which matters if the images are private or under a data handling policy. A cloud service removes the GPU requirement entirely, at the cost of uploading the file. That is the real axis: local GPU versus someone else's hardware.

Licence and upgrade cost

Upscayl is licensed AGPL-3.0, and the repository carries a separate Real-ESRGAN_LICENSE.txt alongside LICENSE, which reflects the upstream model code. The AGPL matters if you modify the app and let users interact with it over a network, or if you redistribute it inside another product. The ncnn backend is described in the FAQ as fully open source under AGPLv3 as well, so the network-facing obligation follows the inference path, not just the UI. This is a description of the licence text, not legal advice; if you are shipping Upscayl inside a commercial product, read the licence and talk to someone qualified.

Upgrade cost is low in the ordinary case. Releases are distributed as AppImage, dmg, exe, deb, rpm, zip and Flatpak, and the Homebrew cask updates through the normal brew mechanism. There is no database, no server component and no migration step in the desktop app. The cost that does exist is undocumented: the README does not describe how to roll back to an earlier release if a new model or binary misbehaves, and it does not describe how the bundled ncnn binaries are validated when update_upscayl_ncnn_binaries.sh runs. Teams that pin versions will be doing so without a documented downgrade path.

Editorial conclusion

Adopt Upscayl if you have a Vulkan-capable GPU, a folder of low-resolution images, and no budget for a commercial upscaler. Skip it if your source images are out of focus or motion-blurred: the README states plainly that Upscayl cannot de-blur or do focus adjustment, and that blurred input is the wrong use case. Before committing, check your GPU against the wiki Compatibility List, confirm the last push date of 2024-12-25 against your tolerance for an unreleased fix, and read the AGPL-3.0 terms if you plan to redistribute the app or the upscayl-ncnn backend inside another product.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes