Desktop app

Preview status: this desktop implementation is under review. Signed downloads are not released yet. Public issue reporting is disabled until its repository is confirmed. The current API publishes no change history; watch notifications will become useful when that upstream feed is implemented.

What the app does#

GPU Ninja is a standalone desktop application that runs on your machine; no browser is required. It shares the website’s catalogue and tools, and can identify the GPU on your machine.

• It identifies your GPU on your own machine, and tells you what your machine can run and which upgrades fit your case.
• It works offline, from the first launch.
• It watches cards, chips, cases and AI models for you, and notifies you when their prices, stock, benchmarks or details change.

It reads only GPU Ninja's public API, exactly as any other client would, and sends nothing about you or your machine anywhere.

Download#

These links always point at the latest release. Every release also publishes a checksum file, SHA256SUMS-<version>.txt, in the same folder, and version-numbered copies of each download, such as GPU-Ninja-<version>-win-x64.exe.

Every macOS build is signed with an Apple Developer ID and notarised by Apple, and every Windows build is code-signed. The Linux AppImage isn't signed.

Supported systems#

There are no native Arm builds for Windows or Linux yet.

Install#

macOS#

Open the .dmg and drag GPU Ninja into Applications. Run it from Applications: the app can only update itself from there. The first time you start a version from somewhere else, it offers once to move itself into Applications.

Windows#

Run the installer. It installs GPU Ninja for your user account without asking for administrator rights, and adds a Start menu shortcut, which Windows needs to show the app's notifications.

Linux#

Make the AppImage executable and run it:

chmod +x GPU-Ninja-linux-x86_64.AppImage
./GPU-Ninja-linux-x86_64.AppImage

Keep the AppImage somewhere you can write to, such as a folder in your home directory, so the app can update itself. If it doesn't start, see Troubleshooting.

Your GPU#

The My Machine screen identifies the graphics cards in your computer.

What detection reads#

Detection asks your operating system which display adapters are installed and reads their PCI vendor and device IDs, which is how operating systems identify GPUs:

• Windows: the system's video controller list, through PowerShell.
• macOS: the system's PCI device registry, then the system profiler's display information if that finds nothing.
• Linux: the PCI device list under /sys/bus/pci/devices/. No program is run.

If none of these finds a GPU, the app falls back to the GPU information its application runtime reports.

Detection runs only when you open My Machine without a saved setup, or when you choose Detect again. It never runs in the background.

It never leaves your machine#

The IDs are matched against GPU Ninja's catalogue on your machine, using the catalogue's search index the app already holds. The app never sends your hardware details anywhere and never writes them to its logs; the one exception is a Report this GPU issue, which you submit yourself on GitHub (see Reporting a problem). They're stored only if you save your setup, and then only your GPU's PCI vendor and device ID, in setup.json on your computer.

What the result means#

On a laptop with both built-in and separate graphics, matched GPUs are listed first, and you can pick another one. Identical cards in one machine are shown once, with a count such as "× 2".

When GPU Ninja's data is updated while My Machine shows an unknown or several-chips result, a Check again with updated data action appears. It matches again without re-reading your hardware.

Your setup#

Alongside your GPU, you can record your case and power supply:

• Case: choose one from GPU Ninja's catalogue, or enter your own measurements: the maximum card length, from 100 to 600 mm, and, optionally, the number of slots it can take, from 1 to 8.
• Power supply: its wattage, from 150 to 3,000 W.

With a setup saved, the app answers:

• What can my machine run: the AI models your card can run, once you've confirmed which card it is. With only the chip known, the app asks you to choose your card first.
• Upgrades that fit my case: cards that fit your case, or that GPU Ninja says to check against it. By default these are current cards with more VRAM than yours. You need to record a case first.
• Power supply: whether your power supply meets each card's recommended wattage. In the upgrade list, a card whose details aren't saved on your computer yet says "Check PSU on the board page" instead.

Fit verdicts for catalogue cases are GPU Ninja's published ones, exactly as on the website. For a case you measured yourself, the app uses the same fit rule GPU Ninja uses to produce every published verdict, and labels the answer "Based on the dimensions you entered". A card GPU Ninja has no verdict for is shown as "Not assessed", never guessed at.

Working offline#

The app ships with a copy of GPU Ninja's search index, so it works the first time you launch it, even with no connection. When it can connect, it fetches current data and keeps a local cache.

• Browsing and search work offline, from the cache or the bundled copy.
• Every screen shows how old its data is: "Updated" with a relative time, or "Bundled data from" a date when it's using the copy that shipped with the app.
• When you're offline, a banner says so.
• Pages you haven't opened before need a connection the first time.
• The cache has a 50 MiB budget. The index, change feed, watched entity pages and compatibility files for your saved board and catalogue case are protected from eviction once cached. Other cached pages can be removed to make room; if protected files alone exceed the budget, they are retained.

The bundled index supports browsing and custom-case fit calculations; it does not contain every detail page or model-compatibility result. Open those pages while connected before relying on them offline. Saving a setup does not by itself download every related page.

When the connection returns, the app refreshes its data on its own.

If GPU Ninja's data moves to a format your version can't read, the app keeps the data it already has and shows "Update GPU Ninja to read the latest data". Installing the latest version fixes it.

Watching and notifications#

Add a card, chip, case or AI model to your watchlist, up to 200 items. The app then checks GPU Ninja's published list of changes a few seconds after it starts, every 6 hours while it's running (including after your computer wakes, once 6 hours have passed), and whenever you choose Check for changes now. If a check fails, for example because you're offline, the app tries again within 15 minutes and notifies nothing until a check succeeds.

You get one notification per change, such as a price drop, a card coming back into stock, a new offer or a new benchmark result. When four or more changes arrive at once, they're combined into a single notification, and the Changes screen lists them all.

The list of changes covers the last 30 days. If the app hasn't checked for longer than that, it re-reads everything you watch and tells you that some changes may have been missed.

The first check after you install the app sets a starting point and notifies nothing. You're never notified twice about the same change. If notifications are off, in the app or in your operating system, changes still appear on the Changes screen.

If something you watch is removed from GPU Ninja, the watchlist shows it as "No longer available" and leaves it for you to remove.

Running in the background#

By default, closing the window keeps GPU Ninja running so it can keep checking. On Windows and Linux it stays in the system tray, with Open, Check for changes now and Quit; on macOS it stays in the Dock. The first time, a notification explains this. Turn off running in the background in Settings to quit when you close the window.

On macOS and Windows you can also choose to open GPU Ninja when you log in. That option isn't available for the Linux AppImage.

Updates#

The app updates itself from download.gpuninja.com. It checks for an update whenever it checks for changes, and when you choose Check for updates. By default it downloads updates in the background and installs them when you quit, or straight away if you choose to install a downloaded update; you can turn automatic downloads off in Settings.

When an update is available, Enable automatic downloads and download update in About saves that preference and checks again to start the download. This also enables automatic downloads for future updates; you can turn them off again in Settings. If the preference cannot be saved, the app shows an error and lets you retry.

Every update is verified before it's installed: the download must match the checksum published with it, and on macOS and Windows it must be signed by the same publisher as the app you have. On Linux the checksum, fetched over HTTPS from download.gpuninja.com, is the only check, because AppImages aren't signed. The app never installs an older version or a pre-release.

Automatic updates are unavailable, and the About screen says why, when:

• on macOS, the app isn't in Applications;
• on Linux, you're not running the AppImage, or the AppImage file isn't writable.

In those cases, download the latest version from the links above.

Every release goes to everyone at once. If a release has to be withdrawn, the app stops offering it within five minutes. If you've already installed it, you stay on it until the fix ships as a newer version. The changelog lists every release.

Privacy#

The app has no telemetry, no analytics and no crash reporting. Nothing about your machine is collected.

The packaged app can connect to only two places: GPU Ninja's public API at gpuninja.com/api/v1/, and download.gpuninja.com/desktop/ for updates. It blocks every other connection, including any its application runtime would make on its own. Its requests carry no cookies, account or install identifier. They identify the app as GPUNinja-Desktop/<version>, and update checks reveal your operating system family, processor architecture and app version. Like any web request, they're processed by Cloudflare.

Your setup, watchlist and settings are stored only on your computer. See the privacy policy.

Data folders#

Everything the app stores is in one folder:

It contains:

• settings.json, setup.json and watchlist.json: your settings, setup and watchlist;
• cache/: cached GPU Ninja data;
• logs/: the app's own logs, at most three files of 1 MB each, deleted after 14 days;
• crash-state.json: recent crash times, used to stop a restart loop;
• <name>.corrupt-<timestamp>.json: saved files the app found damaged and set aside, if any.

Logs never contain your hardware details, setup or watchlist, and your home folder and any email address are masked. The app can open its logs folder for you.

If a saved file is ever damaged, the app sets it aside as <name>.corrupt-<timestamp>.json in the same folder, keeping the three newest for each file, starts from defaults, and tells you if your setup or watchlist was reset.

To remove GPU Ninja completely, uninstall or delete the app, then delete this folder.

Troubleshooting#

My GPU isn't detected#

Open About, then Diagnostics, to see which detection steps ran and what each found.

• On Windows, if the PowerShell step failed or timed out, PowerShell is probably blocked on your machine. Check that the fallback step ran.
• Unknown means GPU Ninja's catalogue doesn't have your GPU's IDs. Choose your card by hand, and use Report this GPU.
• Not a PCI GPU means a GPU built into the processor, such as Apple silicon.

The wrong GPU is shown#

On a machine with more than one GPU, pick the right one from the list.

No notifications#

Check that notifications are on in the app's Settings, then:

• macOS: check System Settings, Notifications, GPU Ninja.
• Windows: the app must have been installed with the GPU Ninja installer, which adds the Start menu shortcut Windows notifications need.
• Linux (GNOME): notifications work, but the tray icon needs the AppIndicator extension. Without it, GPU Ninja keeps running in the background with no visible icon: install the extension, or turn off running in the background in Settings.

The app doesn't update#

The About screen shows why updates are unavailable: not in Applications on macOS, not running as an AppImage, or the AppImage isn't writable. Otherwise, choose Check for updates and look in the logs for the error.

The Linux AppImage won't start#

There are two common causes.

FUSE is missing. AppImages need FUSE 2, which Ubuntu 22.04 and later don't install by default. Install it with your package manager. On Ubuntu 22.04:

sudo apt install libfuse2

On Ubuntu 24.04 and later, the package is named libfuse2t64.

Ubuntu 24.04 and later restrict unprivileged user namespaces with AppArmor, which Chromium's sandbox needs. Allow it for the AppImage with an AppArmor profile. Create /etc/apparmor.d/gpu-ninja, replacing the path with where you keep the AppImage:

abi <abi/4.0>,
include <tunables/global>

profile gpu-ninja /home/you/Applications/GPU-Ninja-linux-x86_64.AppImage flags=(unconfined) {
  userns,
  include if exists <local/gpu-ninja>
}

Then load it:

sudo apparmor_parser -r /etc/apparmor.d/gpu-ninja

Windows warns about the installer#

Windows SmartScreen may warn about a newly released, signed app until it has built up a reputation. The installer is code-signed: check the publisher is GPU Ninja's, then choose More info, then Run anyway.

The data looks out of date#

Every screen shows the age of its data. If you're offline, a banner says so. Behind a corporate proxy, the app uses your system's proxy settings; if requests are blocked or time out, the logs say so. If the app says "Update GPU Ninja to read the latest data", install the latest version.

"Saved data was reset"#

One of your saved files was damaged, so the app set it aside and started fresh. The damaged copy is in the data folder, and you can attach it to a problem report after checking what it contains.

"Saved data is from a newer version of GPU Ninja"#

You've installed an older version than the one that last saved your data. The app leaves your files untouched and can't save changes until you install the newer version again.

The app crashes#

If the app crashes, it offers Restart, Report a problem and Quit. After three crashes within 10 minutes, it stops offering a restart. If the window's contents crash, the app reloads them once; if that happens again within a minute, it shows a page with Try again and Report a problem. If its graphics process crashes repeatedly, the app turns off hardware acceleration from the next launch, and Settings shows a control to turn it back on. If the window stops responding for 10 seconds, you can wait or reload it.

Reporting a problem#

Report a problem, in the app, opens a pre-filled issue on GitHub. It includes the app version, Electron version, operating system and version, and processor architecture and, if you choose, the last error's message and stack trace, with your home folder and email addresses masked. It never includes your hardware, setup, watchlist or logs. Nothing is sent until you submit the issue yourself, and GitHub's privacy policy applies to what you submit.

Report this GPU, shown for an unknown GPU, opens a pre-filled issue the same way, with the GPU's PCI vendor and device IDs (and subsystem IDs, when known), its name as your system reports it, the app version and your operating system, so we can add it to the catalogue.

For anything else, see Support.