HiPixel: a native macOS shell around Upscayl's super-resolution models

A SwiftUI interface over someone else's ncnn engine

HiPixel is not a new super-resolution engine. The project description calls it a native macOS application for AI-powered image super-resolution built with SwiftUI, and the README is more specific about where the modelling actually comes from: four models shipped from Upscayl, plus the upscayl-bin binaries fetched on first launch. The honest way to read this repository is as an interface layer. Someone wrote the app, the settings pane, the notifications and the drag-and-drop workflow, then pointed them at an existing ncnn inference stack instead of training anything new.

Two build facts set expectations early. The badges name Swift 5.9 and macOS 13.0 or newer, so this is neither cross-platform nor an older-macOS app. The license is AGPL-3.0, which matters more than usual here precisely because the code is a frontend to another project's components: anyone planning to bundle HiPixel has to read both licenses rather than this one.

The top level of the repository is short: `HiPixel.xcodeproj/`, the `HiPixel/` app directory, `Localizable.xcstrings`, `README.md` and `README.zh-CN.md`, `LICENSE`, `screenshot.jpeg`, `buildServer.json` and `.markdownlint.json`. The string catalog and the Chinese README show the app is localized, and buildServer.json is the file Xcode Cloud reads to define build actions. The repository reports 1,155 stars and 48 forks with no open issues, which says more about attention than about quality.

Four built-in models, and a folder for your own

Model selection is the simplest decision in the app, and the model IDs are the clearest way to talk about it:

upscayl-standard-4x
upscayl-lite-4x
high-fidelity-4x
digital-art-4x

Standard is the general photo path, Lite trades detail for speed and lower resource use, High Fidelity is the detail-preserving option, and Digital Art targets illustrations and anime. The README also lists double processing (running the upscale twice in a single pass), optional TTA for better quality, EXIF preservation so camera and orientation data survives, and manual GPU selection with a custom tile size.

Custom models go further. Each one is a pair of files in ncnn format, the same format Upscayl uses:

<name>.bin
<name>.param

You drop the pair into a folder, select that folder in Settings or pass it through the `customModelsFolder` URL parameter, and pick the model from the list. The precedence rule is the part worth remembering: when a built-in and a custom model are both specified, the custom one wins. Nothing in that sentence warns you, so a file named `upscayl-standard-4x.bin` will quietly shadow the bundled model. Since ncnn pairs a binary with a parameter file describing its tensor layout, a mismatched pair is the first thing to check when a custom model refuses to load.

First launch fetches the binaries, and checksums them

HiPixel keeps its download small by leaving the heavy parts out of the app bundle. On first launch it pulls upscayl-bin and the AI models over the network, verifies every download with SHA256 checksums, and stores the result here:

~/Library/Application Support/hipixel/

Updates to those resources are checked automatically at launch, and the README points at a manual check in the Advanced settings tab.

That design has two consequences a user hits quickly. A first run on a machine without network access has no models at all, so the app is not usable offline until it has been seeded once. And because the resources are external and checksum-verified, a corrupted or tampered download is rejected rather than silently loaded, which is a small thing that most hobby apps skip. It also means the failure mode when a model misbehaves is a directory: clear the Application Support folder and let the app fetch the resources again.

The trade is that HiPixel depends on someone else's release artifacts staying reachable. The README describes the download and its verification but does not document how large the models are or what happens when the fetch fails partway through.

hipixel:// as the real automation surface

This is where HiPixel separates itself from a plain upscaler. The app registers a URL scheme whose query parameters override whatever is set in the interface, so scripts and other apps can drive it. The basic form takes one or more paths:

hipixel://?path=/path/to/image1&path=/path/to/image2

`path` is required, accepts files or folders, and repeats for multiple inputs. The README documents `saveImageAs` with PNG, JPG, WEBP or Original, `imageScale` with multipliers such as 2.0, 4.0 and 8.0, and an `imageCompression` level, plus the `customModelsFolder` parameter used above. The documented parameter names are:

path
saveImageAs
imageScale
imageCompression
customModelsFolder

Alongside the URL scheme there are two other automation paths. Folder monitoring picks up new files added to designated directories. Apple Shortcuts support arrived in v0.4.1 as AppIntents, exposing an "Upscale Images" action with the processing options configurable, and the same release added a Zipic integration for compressing results after upscaling.

One detail from those release notes changes how the save setting behaves. The Manual Save Control option added in v0.4.1 routes images processed by direct user actions to a temporary directory, while automated operations (URL scheme, Shortcuts, folder monitoring) are untouched and still save normally. That is a sensible split, and it means enabling manual save will not stall a background pipeline.

What the release history says about where the effort went

Three releases tell a consistent story about the project's direction. v0.4.1 on 2025-11-03 added URL scheme parameters and AppIntents support, reworked the comparison viewer with a reprocess button, trackpad pinch-to-zoom from 1x to 5x, drag-to-pan and a zoom controls panel, and introduced the manual save control. v0.4.2 on 2025-11-10 went after the desktop presence: a menu bar button, an option to hide the Dock icon, silent launch so the main window does not open at startup, SF Symbols icons across menus and buttons, and accessibility work. It closed issue 7.

v0.4.3 on 2026-03-13 made manual save the default for new installs, with a hint after the first save that switches to automatic saving in one click, and changed completion notifications to include the save destination path. It also added Homebrew installation.

The interesting detail is what sits around those dates. The last push to the default branch was on 2026-07-13, roughly four months after v0.4.3 shipped. Work is landing on main faster than release tags appear, so the menu bar, silent launch and notification features described in the release notes are not the whole current surface, and the changelog is not a complete picture of what the app does today.

Where HiPixel is the wrong choice

The platform constraint is the obvious one. macOS 13.0 or newer, SwiftUI, no Windows or Linux build mentioned anywhere in the README, so a cross-platform team has to keep using Upscayl directly. The README is explicit that HiPixel aims to complement Upscayl rather than replace it, and given that it runs Upscayl's binaries and models, that positioning is the accurate description rather than a courtesy.

The documentation is uneven in a way that matters for automation. GPU selection, tile size, TTA and double processing are exposed in the interface but are not documented as URL parameters, so a script can set scale, format and compression while the expensive tuning knobs stay manual. Nothing in the README describes batch scheduling, retry behaviour, or what happens to a queue when the folder monitor and the URL scheme both hit the same directory.

Double processing and TTA deserve a caution as well. Both buy quality with time, and they apply to every image in a batch, so enabling them on a monitored folder turns a cheap job into an expensive one with no per-image cap described anywhere. EXIF preservation covers camera and orientation data, but the README does not say what happens to other metadata. Finally, for anyone planning to ship HiPixel inside a product, AGPL-3.0 plus a dependency on externally downloaded Upscayl binaries is a licensing conversation to have before writing any integration code, not after.

Editorial conclusion

HiPixel is worth a look if you work on a Mac, upscale often enough to want folder monitoring and a URL scheme, and would rather not drive Upscayl's own interface. It is the wrong tool on Windows or Linux, and the wrong dependency for a product you intend to ship without reading AGPL-3.0 first. The docs settle model selection, the automation surface and the save workflow; they do not settle download size, tile and GPU tuning guidance, or which UI options are reachable from a URL. Verify three things in order: launch it once with a network connection so the models land in Application Support, try one image through the comparison viewer at your intended scale, and check the Advanced tab before wiring folder monitoring into a pipeline.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. okooo5km/HiPixel on GitHub
3. Project website
4. README
5. Releases