Installation¶
pgNimbus ships for Windows, macOS and Linux. Windows is the primary target and the most polished. The macOS and Linux builds are early beta.
Windows¶
Microsoft Store, recommended¶
The Store package is signed by Microsoft and updates itself, so there are no SmartScreen warnings and nothing to re-download by hand.
Get pgNimbus on the Microsoft Store
WinGet¶
This installs the same Store package, so it carries the same signature.
Portable zip¶
Download pgNimbus-<version>-win-x64.zip from the
releases page, or
pgNimbus-<version>-win-arm64.zip for a Windows on Arm device, such as a
Snapdragon laptop. Unzip it anywhere you like, and run
PgNimbus.App.exe from the folder inside it, named like the zip.
The x64 zip also runs on Arm under emulation, but starts slower. Nothing is installed and no administrator
rights are needed. To update, replace the folder with the new release's. Your
connections and settings live in %AppData%\pgNimbus, not in the folder, so
they carry over.
Releases up to 1.0.0 also shipped an MSI installer. If you installed one, remove it under Settings › Apps › Installed apps and use the Store or the zip instead: the MSI gets no further updates.
The zip is unsigned
pgNimbus is a free project with no revenue, so it does not buy a code signing certificate. SmartScreen will warn on first run; click More info then Run anyway. If that bothers you, use the Store or WinGet path above. The Store re-signs the package for free, which is why it is the recommended route. You can also verify the download's provenance instead of trusting the warning either way.
macOS¶
Apple Silicon only, on macOS 14 Sonoma or later. Download pgNimbus-<version>-macos-arm64.dmg from the
releases page. Open the disk
image, drag pgNimbus onto the Applications folder beside it, then eject the
image. Running the app from the mounted image works, but it disappears the
moment you eject.
The build carries an ad-hoc signature instead of an Apple Developer ID one, so macOS asks about it the first time you open it:
Right-click (or Control-click) pgNimbus in Applications, choose Open, then Open again in the dialog.
Double-click pgNimbus and dismiss the warning. Open System Settings → Privacy & Security, scroll to the security section, and click Open Anyway next to the message about pgNimbus.
You do this once per installed version. Later launches open normally.
Saved passwords and updates
macOS ties a Keychain item to the app that created it. Every ad-hoc signed version counts as a different app, and pgNimbus does not show the Keychain permission prompt. After an update, a password saved by the earlier version can stop loading. The connection stays in your list, its password field is empty and the connection dialog shows a password storage warning. Typing the password again does not fix it.
To fix it, open Keychain Access, search for pgNimbus, delete the items
with that name, then enter each password again in pgNimbus. Builds signed
with an Apple Developer ID keep one identity across versions, so this stops
once notarized builds ship. The first notarized version is a new identity
too, so expect to do this one more time when you move to it.
If macOS says the app is damaged
That dialog means the download carries no signature at all, which is what 0.11.1 and earlier shipped. There is no Open Anyway path out of it. Either download a later build, or clear the quarantine flag by hand:
The command works as a fallback on any version, including from Downloads if you have not moved the app yet.
No Intel build
GitHub retired its last Intel macOS runner in December 2025, so there is no
hosted way to build an osx-x64 binary. Apple Silicon only for now.
Linux¶
x64 and arm64 builds, in three formats, all on the
releases page. All three
need glibc 2.35 or newer, so Ubuntu 22.04, Debian 12 or a later release. On an
older system the app stops at once with version `GLIBC_2.xx' not found.
Works on any such distribution and installs nothing. The file is named
pgNimbus-<version>-x86_64.AppImage for x64 and
pgNimbus-<version>-aarch64.AppImage for arm64.
AppImages built after 1.2.0 carry update information, so a tool such as
AppImageUpdate can fetch the
next release and download only what changed. The .zsync file beside each
AppImage on the releases page is what that tool reads; you do not need to
download it yourself.
The package also adds pgNimbus to your application menu. Its dependencies are the X11 libraries Avalonia needs plus fontconfig; the rendering stack itself is bundled.
Verifying a download¶
The direct downloads are unsigned, but every release asset carries
signed build provenance.
Plain --repo accepts an attestation from any workflow or ref in the
repository, so pin the check to the release workflow and the tag you
downloaded:
gh attestation verify pgNimbus-<version>-win-x64.zip --repo Shman4ik/pgNimbus \
--signer-workflow Shman4ik/pgNimbus/.github/workflows/release.yml \
--source-ref refs/tags/v<version>
Without the gh CLI, check the download against SHA256SUMS.txt from the
same release instead. That file is attested too, so verifying the checksums
still proves the release build produced them:
Each release also ships a CycloneDX SBOM
(pgNimbus-<version>-sbom.cdx.json) listing every bundled dependency.
Where pgNimbus keeps its files¶
| What | Location |
|---|---|
| Connection profiles, saved queries, history, settings, workspace | <appdata>/pgNimbus/ |
| Crash log | <appdata>/pgNimbus/logs/pgnimbus.log |
| SSH host keys you accepted | <appdata>/pgNimbus/known_hosts, in OpenSSH's format. See host keys. |
| Passwords | DPAPI-encrypted files in <appdata>/pgNimbus/credentials/ on Windows; Keychain on macOS; Secret Service via libsecret-1.so.0 on Linux. Unavailable storage uses session memory with a visible warning. Never the profile file. Legacy unencrypted .cred files (macOS and Linux) are all migrated when the connection dialog first opens, then removed only after verification. See credential storage. |
On Windows <appdata> is %AppData%; the Microsoft Store version may keep the
folder under %LocalAppData%\Packages\DmitriiShmanev.pgNimbus_5cjm84wd2pj14\LocalCache\Roaming
instead. On macOS and Linux it is ~/.config, or $XDG_CONFIG_HOME when that
is set. Uninstalling leaves the folder in place; the
privacy page says how to remove it and what
each file holds.