One Release, Five Package Managers: Making Installation and Updates Easy for Users

Installing is easy; updating is what really matters. How to deliver an app from a single tag through Homebrew, winget, Scoop, Flatpak and Docker.

Releasing a new version of an app is easy. A release shows up on GitHub, you attach the archives, and you’re done. But a user who downloaded your app half a year ago doesn’t know the new version exists. And it’s not their fault that it never reaches them; it’s the fault of how you delivered the app in the first place.

Installation is a one-time thing. The real difference between “download it from the website” and properly distributed software is updates: who runs them, how easily, and whether you can roll back. I worked through this for my own tools (OmniDB, PgArachne, pg_procrustes, pg_dbml and others) and ended up with a split that has no single answer for every platform.

How I choose

For each platform I asked myself four questions:

macOS: Homebrew

On macOS, Homebrew makes sense for everything. A formula is for the command line, a cask for apps with a graphical interface.

brew install --cask heptau/tap/omnidb   # GUI (cask)
brew install heptau/tap/pg-procrustes   # CLI (formula)
brew install heptau/tap/pg-dbml         # CLI (formula)
brew upgrade                            # update everything

The decision worth some thought is a custom tap versus the official repository. A custom tap (heptau/tap) works right away: all you need is a GitHub repository and a few files in it. You only get into the official homebrew-cask once the project is well known enough and, above all, once your app is signed and notarized by Apple (which means a paid Apple Developer account).

Homebrew doesn’t bypass Gatekeeper, by the way. It marks a downloaded app with the quarantine flag just like a browser does, so macOS checks it on first launch. There used to be a --no-quarantine switch that let users turn quarantine off, but as of Homebrew 5.0.0 it’s deprecated, because Homebrew doesn’t want to make it easier to circumvent macOS security features. Unsigned casks are flagged as deprecated, and the official repository was supposed to drop all casks that Gatekeeper rejects starting in September 2026 (I verified this in the Homebrew 5.0.0 announcement, not in practice).

The takeaway for you is simple: signing and notarization are your job, not Homebrew’s. Without them, Gatekeeper blocks the app on first launch no matter how it was installed, and you won’t get into the official repository. In your own tap nobody removes a cask, but Gatekeeper on the user’s machine applies all the same.

One thing that helps users no matter how they installed the app: if you already have it installed manually (by downloading a .dmg or a zip) and want Homebrew to manage it from now on, you don’t need to delete it and download it again. Just run:

brew install --cask --adopt heptau/tap/omnidb

The --adopt switch takes over an existing app in /Applications if it’s identical to the one the cask would install, and from then on Homebrew manages it, so brew upgrade will update it. According to the documentation, the existing files must be identical to the installed ones, so it’s mostly useful when you have the same version as the cask. It can’t be combined with --force. For an author this is good news: users who downloaded the app from the website can be moved over to Homebrew without a reinstall.

Windows: winget and Scoop

winget is a package manager that ships with both Windows 11 and Windows 10 (since version 1809, as part of the App Installer component). The user types winget install and winget upgrade and needs nothing else. For you it means submitting a manifest as a pull request to the microsoft/winget-pkgs repository. The requirements are a stable installer URL and a silent install. Approval is slower than with your own tap, but once the first package is in, later versions can be submitted automatically.

I have a working example with the graphical app OmniDB. The user types:

winget install heptau.OmniDB
winget upgrade heptau.OmniDB

For a graphical app, the most natural choice is a real installer (.exe or .msi), because it has to create shortcuts, register an uninstaller and so on. That’s why OmniDB builds an NSIS installer at release time, and a script generates the manifest from it and from the checksums. The manifest consists of three YAML files (version, installer and description). The installer file is the most important one:

PackageIdentifier: heptau.OmniDB
PackageVersion: 5.5.0
InstallerType: nullsoft
Scope: machine
InstallModes:
  - interactive
  - silent
  - silentWithProgress
UpgradeBehavior: install
Installers:
  - Architecture: x64
    InstallerUrl: https://github.com/heptau/omnidb/releases/download/v5.5.0/OmniDB-win-x64-setup.exe
    InstallerSha256: …
ManifestType: installer

The silent part is the “silent install” I mentioned; without it, winget upgrade couldn’t run without user intervention. The heptau.OmniDB identifier follows the Publisher.Name format, which is a winget convention.

Winget has one property I haven’t seen in other package managers: it can update even an app the user installed manually, by downloading the installer from the website. This works because every classic Windows installer writes an entry to the registry for the “Apps & features” list (ARP, Add/Remove Programs): name, publisher and version. Winget reads these entries and tries to match them with packages in the repository. When it succeeds, winget list shows the manually installed app alongside the others, and winget upgrade can update it as if winget had installed it from the start.

That leads to some practical advice for the author: make sure the name and publisher in the installer match the manifest, or list them in the manifest in the AppsAndFeaturesEntries field. The matching relies on names and versions, and when it fails, the app doesn’t show up in winget upgrade or has the version “Unknown”. So don’t treat it as a guarantee, but as a bonus you have to keep an eye on. Homebrew has something similar, but different: it can’t find the app on its own, and the user has to “adopt” it manually (see the --adopt command in the macOS section).

The release itself then finishes automatically: a script creates a branch in the heptau/winget-pkgs fork and opens a pull request with the new version. The first package had to be submitted to winget-pkgs by hand, because a new package goes through a different approval than a version bump. The script knows this and refuses to automatically submit a package that doesn’t exist upstream yet.

For command-line tools you don’t need an installer. Winget knows the portable type (a standalone .exe) and, since version 1.4, also zip, from which it picks up a nested portable file. So an archive you already publish is enough, and the manifest just has a different type. This is how it would look for the archive pg_procrustes already publishes (I haven’t submitted it to winget-pkgs yet; this is just a demonstration):

InstallerType: zip
NestedInstallerType: portable
NestedInstallerFiles:
  - RelativeFilePath: pg_procrustes.exe
Installers:
  - Architecture: x64
    InstallerUrl: https://github.com/heptau/pg_procrustes/releases/download/v0.6.1/pg_procrustes-0.6.1-windows-amd64.zip
    InstallerSha256: 6d361058befc5176516b52017428abd271d41a2b2d5192968b73097de3b549bc

Winget unpacks such a tool into the user’s directory and exposes it on PATH, with no admin rights and no installer. So far I’ve only tried this route at the documentation level, not in a real pull request to winget-pkgs, so check the exact field names against the manifest schema before submitting.

Scoop is a good alternative for the command line and portable apps. It installs into the user’s directory without admin rights, and you can set up your own bucket (the equivalent of a tap) in a few minutes.

scoop bucket add heptau https://github.com/heptau/scoop-bucket
scoop install pgarachne
scoop update pgarachne

Chocolatey deserves a mention too: it’s an older package manager used mainly in corporate environments. For new projects, though, winget and Scoop are more convenient.

Linux

Here the paths for GUI and CLI apps diverge.

Graphical apps: Flatpak

For apps with a window, Flatpak is a reasonable choice. The app installs from Flathub, updates with flatpak update and runs in a sandbox. The sandbox is precisely what matters for a PostgreSQL client. The app can’t see ~/.pgpass or Unix sockets on its own, so the permissions have to be listed explicitly in the manifest (I write about this in more detail in the article Sandboxed Apps: When Isolation Cuts the Database Off From .pgpass).

I’ll mention Snap and AppImage in a single sentence: Snap is tied to Canonical, and AppImage has no update mechanism of its own.

Command line: Homebrew

At this point I originally considered .deb and .rpm packages. I ran into two problems:

That’s why on Linux the pragmatic choice for me is Homebrew. It’s the same command as on macOS, it installs into /home/linuxbrew/.linuxbrew, needs no root and doesn’t clash with the system package manager. And the formula can be exactly the same. My PgArachne formula just has on_macos and on_linux blocks pointing to precompiled archives from the GitHub release:

on_linux do
  if Hardware::CPU.arm?
    url "https://github.com/heptau/pgarachne/releases/download/v#{version}/pgarachne-linux-arm64.tar.gz"
    sha256 "…"
  else
    url "https://github.com/heptau/pgarachne/releases/download/v#{version}/pgarachne-linux-amd64.tar.gz"
    sha256 "…"
  end
end

No compilation, just downloading a ready-made binary and checking it against the checksum.

Homebrew on Linux does have downsides, though, and it’s only fair to name them:

Server: the PgArachne example

A server updates differently from a desktop. Updating the gateway that applications connect to should be controlled, not silent. I don’t want it to switch itself to a new version on a Friday evening.

Homebrew handles this well:

brew install heptau/tap/pgarachne
brew services start pgarachne      # creates the service
brew upgrade pgarachne             # new version
brew services restart pgarachne    # restart after the update

On Linux, brew services creates a systemd user service. For it to run without a logged-in user, you need to enable loginctl enable-linger once. If you want to automate updates, it’s enough to call brew upgrade from cron or a systemd timer, but deliberately and at a time you choose.

What about git pull?

I also considered the simplest solution: keep a clone of the repository on the server and update it with git pull. There are two variants, and both have a catch.

Interestingly, Homebrew actually does this too: a tap is a git repository, and brew update is essentially git pull. The difference is that the repository holds only small text descriptions (formulas), not binaries. The binaries themselves are downloaded from releases, verified against a checksum, and the version is chosen by platform. So it’s git pull for the metadata and a download for the data, and it’s that split that makes it a usable solution.

For development, git pull is enough. For production I’d use it only via a tap, not directly.

Docker: the shorter path for servers

For server applications, the least painful update is often a Docker image with a version tag:

services:
  app:
    image: ghcr.io/your-account/your-app:2.0.2

An update means changing the version number and running docker compose pull && docker compose up -d. A rollback is the same thing with the previous number. It’s the most straightforward way to manage versions, but it assumes you already have Docker on the server and use it.

I’ll admit I don’t publish a PgArachne image yet. It’s another channel that GoReleaser could handle from the same tag, and if I add it, it’ll be just another block in the configuration.

What about web apps (PWAs)?

With PWAs the situation is the opposite of everything above: they don’t need to be updated, because the update happens the next time the page loads. A package manager can’t improve anything there. Only installation remains, and even that takes two clicks in a browser.

Still, I wondered whether you could install the app’s icon through Homebrew, so that it sits next to your other apps and in your Brewfile. On macOS this turns out to be surprisingly simple. When you add a PWA to the desktop in Safari, you get an .app that contains only an Info.plist (with the whole web app manifest), an icon and a signature. No executable code; the system supplies that. Such an app can simply be zipped up and published as a cask. For now it’s only a demonstration (I’m not publishing a Lumifex release with this file yet, so the URL and checksum are placeholders):

cask "lumifex" do
  version "1.0"
  sha256 "…"

  url "https://github.com/heptau/lumifex/releases/download/v#{version}/Lumifex.app.zip"
  name "Lumifex"
  homepage "https://lumifex.80.cz/"

  depends_on macos: ">= :sonoma"

  app "Lumifex.app"
end

I tried it, and a copy with the quarantine flag (as after downloading from the internet) launches without a single error, even though it’s only signed ad hoc. But I’ve only tested it on the same Mac where the bundle was created, so take it as a verification with a caveat.

It’s worth being honest about what you gain and what you don’t. Updates still happen inside the PWA, and brew upgrade changes nothing about them. What you get is a single install command, an icon in Launchpad and the ability to keep the app in a Brewfile. I wouldn’t expect anything this simple on Windows and Linux. A shortcut that launches the browser in app mode could be created through Scoop or a small installer, but I haven’t tried it, and on Linux a Flatpak would be a wrapper with its own runtime, not a link.

Comparison

RouteInstallUpdateRollbackMaintained by 
Manual downloaddownload and unpackmanualmanualuser
Homebrew (macOS, Linux)brew installbrew upgradebrew install a specific version (limited)me (tap)
wingetwinget installwinget upgradespecific versionme + reviewer
Scoopscoop installscoop updatescoop resetme (bucket)
Flatpakflatpak installflatpak updateflatpak update --commitme + Flathub
Dockerdocker pullchange the tagchange the tagme (registry)

How to make it not extra work

Five channels sound like five tasks with every release. The answer is automation: all artifacts should generate themselves from a single tag. For that I use GoReleaser, which builds binaries for all platforms from a single codebase, packs them into archives and computes the checksums.

The base of the PgArachne configuration looks like this:

version: 2

project_name: pgarachne

builds:
  - id: cli
    main: ./cmd/pgarachne
    binary: pgarachne
    env:
      - CGO_ENABLED=0
    goos: [darwin, linux, windows]
    goarch: [amd64, arm64]
    ldflags:
      - -s -w
      - -X github.com/heptau/pgarachne/internal/version.Version={{ .Version }}

archives:
  - id: cli-archive
    ids: [cli]
    name_template: "{{ .ProjectName }}-{{ .Os }}-{{ .Arch }}"
    formats: [tar.gz]
    format_overrides:
      - goos: darwin
        formats: [zip]
      - goos: windows
        formats: [zip]

checksum:
  name_template: checksums.txt

This is the real configuration. The tap formula is then generated by my script from the checksums GoReleaser produces. But GoReleaser can do more than that: it can create the formula, the Scoop manifest and the winget manifest itself and push them to the appropriate repository:

brews:
  - repository:
      owner: heptau
      name: homebrew-tap
    homepage: "https://www.pgarachne.com/"
    description: "PostgreSQL JSON-RPC gateway"

scoops:
  - repository:
      owner: heptau
      name: scoop-bucket
    homepage: "https://www.pgarachne.com/"
    description: "PostgreSQL JSON-RPC gateway"

(I include this second part as a showcase of what’s possible; I don’t use it for PgArachne yet.)

What can’t be automated, or only with difficulty: Apple’s notarization, approval on Flathub and the pull request to winget-pkgs, where a human or a bot always sits at the end verifying the package.

Conclusion

My recommendation, which is what I use now:

The common core is one thing: updating is a product feature, not an afterthought. Users should get it as easily as installation, and you should get it from a single tag with no manual clicking.