One correction: Homebrew is not Mac-only, as it also supports Linux.

However, to answer your question more directly: The goal should be to make it as easily-packable and portable as possible, which means no crazy build system (I always use POSIX make with a Makefile and a config.mk-file with a configure-script that simply modifies the variables in config.mk for a given target system (see here), but your mileage may vary) and reasonable dependencies. Use semantic versioning, especially for libraries.

For hosting: I would recommend setting up your own website with your own git or gitlab instance where you set version as tags and publish tarballs with hashes as repository-states at a given tag. It is relatively cheap to do that. As a backup, you can set up mirror repositories on GitHub and so forth, and it will work just fine, given each tag will also be mirrored as a “release”.

Over the years I have learnt that you do not get around working with package maintainers. Ask them what you can improve to make your tool easier to package and actively send pull requests/patches to package your tool in popular distributions. Of all distributions, Debian/Ubuntu is the most difficult of all to get into and almost impossible without inside help, whereas other distributions make it very easy.

I personally do not include version checks into my tools, but it can be done simply enough if you can live with the extra cruft in your binary (network code, parsing, etc.). In C, I would have a Makefile that contains a variable VERSION that is passed to the C-preprocessor as -DVERSION=$(VERSION), which in turn can be used in the code to compare it against the current online version.

Regarding packaging again: I have never met an unkind package maintainer and the work they do is mostly unthanked for. One e-mail straight out asking to be included in the package sources often does wonders. :)

The topic of Windows comes up here and there: I would target MinGW-W64 and not even start trying to port to MSVC. The advantage with MinGW-W64 is that you can use the usual POSIX tools like make and, compared to Cygwin, obtain true native binaries.

Personally speaking, I don’t see the benefit of auto-updates here. I’d suggest distributing it as source, so that it can be packaged by third-parties into Linux distros, into the FreeBSD ports tree, etc.

Then, updates can be handled by those downstreams as appropriate.

As a user, I don’t want auto-updates. I’d rather the package manager did it or I did it manually. For most command line tools I’m happy to manually download binaries from the project website or github releases if my package manager doesn’t have an acceptable version.

For getting into package repos, just use some language with a clear standard toolchain for packaging binaries, use that toolchain and politely email the repo maintainers. Rust and Go have obvious toolchains that produce static binaries. If you use unusual dependencies then it could still be a pain to get into package repos because the maintainers will often want to package up the libraries separately from your tool (which is a bit shit, because then you don’t get control over what exact version your dependencies are).

Edit: if your tool requires regular updates to continue to work (e.g. it depends on some internet service whose API changes regularly) then a warning that I should update when I run it is fine if it has to connect to the internet anyway. Ideally, the tool shouldn’t talk to your server unless it has to.

If you do not need to support Win32, you could package it as a Nix flake. Nix is a build-from-source package manager, but anything upstreamed to nixpkgs will be built once by hydra.nixos.org and then anyone who needs the exact same version of the package will be able to download the build artifacts rather than build them locally.

Another option would be to add Nix flake configs to the tool’s repo, which would enable users to try the command without installing it via nix run git+https://your.git.host/ashishb/your-app-repo#app-name (which you could wrap in a script in /usr/local/bin for ease of use). Nix then automatically downloads the app and runs it. The user automatically gets the latest version unless they pin it.

Caveats:

1. Your users are much more likely to have brew, apt, or docker installed than nix. Though, nix is not too hard to install, and doesn’t interfere with the system when you’re not using it, so it’s not a huge ask.
2. Using nix-env may require users to add Nix paths to their PATH, so it’s not a single-command install per se.
3. With a nix flake outside nixpkgs, users probably won’t benefit from the binary cache, so they’ll end up building your app from source locally. You could probably work around this, but not in a way that makes it still single-command.

I’ve been exploring this problem with my https://datasette.io/ project for the last five years now. Here’s everything I’ve tried so far:

• It’s written in Python, so I started out with pip install datasette or pipx install datasette - fine for people with Python familiarity, terrible for everyone else: https://docs.datasette.io/en/stable/installation.html#using-pip
• I publish a Docker package, but I don’t think that’s helpful for anyone who doesn’t habitually use Docker: https://docs.datasette.io/en/stable/installation.html#using-docker
• I got it into Homebrew. This is by far the most usable installation mechanism… for Mac users who have already installed Homebrew! brew install datasette - https://docs.datasette.io/en/stable/installation.html#using-homebrew

Those were my first attempts. More recently I’ve tried some more sophisticated approaches:

• I built an Electron Mac app - https://datasette.io/desktop - that wraps the command-line and adds a web-based interface on top of it - and bundles its own installation of Python using https://github.com/indygreg/python-build-standalone - I wrote about how I got that working in detail here: https://simonwillison.net/2021/Sep/8/datasette-desktop/
• I got it working in WebAssembly so people could run it entirely in their browser without installing anything at all! https://lite.datasette.io/ - see also https://simonwillison.net/2022/May/4/datasette-lite/
• Most recently, I’m putting the final touches on a SaaS version of the software, so people can pay me to use a private, hosted version without needing to figure out how to install and manage their own server: https://datasette.cloud/

The only avenue I haven’t fully explored is creating a compiled standalone executable that bundles Python under the hood. https://github.com/indygreg/PyOxidizer is a leading contender for that, should I decide to go in that direction.

I’m not 100% happy with any of these solutions. This is such a difficult and persistent problem!

I’d suggest that auto-update is asking too much–have a functionality to check if updates are available, but leave the sysadmin work to the users and the ecosystem managers. If you do that, then you can just throw up a pile of binaries under Github releases or whatever.

Have you looked at Flatpak? https://flathub.org/ for example. You can also host your own, but flathub is the de facto standard.

I always prefer to install utilities, whether GUI, TUI, or CLI, from my package manager. Only as a fallback, I use statically linked binaries, such as those produced with Go or Rust. I will not use Snap, Flatpak, AppImage, Docker, or any of the rest. I only use pip in a virtual env when creating Python tools. I think a Google Play for Linux (Snap/Flatpak) should be very aggressively avoided.

There are established mechanisms for software distribution on Linux, they have worked and been reliable for the last few decades, and I don’t believe there’s any reason to switch.

• Developers shouldn’t distribute their own software
• Developers: Let distros do their job

FRIGN’s advice is also fantastic.

With regard to option 2, getting your package into some package repos for a few major distributions does give you roughly this (modulo the limitations of each distro). I (at least notionally) try to target Gentoo, Debian, Ubuntu (specifically, though if you get into Debian properly then you will eventually be ported into Ubuntu), and Arch Linux when I’m not developing something tied to some language or environment’s package manager. But you might add one each of the Mac and Windows package management tools as well.

Edit: doing this (and also specifically structuring your program so that it is easily packageable), and providing .deb’s for direct download, means that distro maintainers for other distros will tend to be pretty willing to do the ‘last mile’ packaging, getting you fairly complete coverage.

If you can drop the auto updates and just distribute self contained executable, the cosmopolitan might be an interesting option.

I think the auto-update will be the hard part. Absent auto-update, shipping binaries written in Go or Zig is pretty easy (since they both have stellar cross-compilation support). You can also package up python using zipapp so that all the user needs to have pre-installed is python, and you ship your app self-contained with all its dependencies.

Auto-update is hard because each OS will do its own thing for package management. You could distribute through a third-party package manager, though. Both nixpkgs and Homebrew can be installed onto an existing Linux or macOS install.

yt-dlp has an --update flag which will cause the binary to check for updates and try to update itself, but you need to be careful with mechanisms like that to avoid security issues.

1. let people update it with their regular packages, so they never get broken by a bug fix the day of a big demo
2. regular package managers have done this. The package manager infrastructure gets go or cargo installed so the end user doesn’t need to, and the end user gets a single command they are used to using, that gets them your tool.

Apt and brew can be both fed by the same tarball. You are distributing open source, so distribute source! This comment is really good: https://lobste.rs/s/wk9qye/best_way_distribute_foss_tool_2023#c_gdpsei And if you use an expected build mechanism, even for python packages, then you might end up packaged on a dozen different platforms you’ve never even thought of.

Compile to a binary or single script and provide instructions to download and copy to /usr/bin or equivalent location. Still the cleanest IMO

Nobody uses package managers on Windows and they’re a last resort on macOS so you are gonna have to roll your own auto-update unfortunately.

On the Linux side, tbh pretty much the only software I’ve interacted with that “just works” and isn’t a nightmare of broken shit has been software that entirely sidesteps the traditional Linux ecosystem. So software that is either written in Go, or distributed as containers. With Go, you go to the project’s github, download a 100% static linked binary, and it works 100% of the time forever. Containers are less reliable because you have a gigantic runtime, but you can at least find static linked versions of podman etc.

Beyond that you’ll have to accept that your software will not work a significant % of the time for your users for reasons that are entirely out of your control.

For musicians who want to distribute their songs on multiple streaming platforms there exist services which do exactly that: provide a single, unified interface and take care of publishing on different services, adopting to different rules behind the scenes. I was wondering if a similar service exists for FOSS.

Have a source repository, build a package for the distribution that’ you’re using, and allow other distro communities to create similar packages if they’re interested (which in truth, they’ll probably not be).

I have a couple of small C applications like that and, outside of a couple of enthusiasts from Fedora, nobody was interested in packaging it, and that was fine. I have it for myself where I need it and that’s enough for me.

Create a repository, maybe a GitHub morror.

Make your software easy to build and deeply.

Use tags or some rest standard way for robes, sane version numbers.

Then making packages, installers and even auto updates on windows if needed all are easier to do both by you and other people.

Help porters when you can. Even in obscure platforms. Usually that has a lot of positive side effects even when not initially obvious.

Still make binaries available, even when you don’t consider it the best way to install your software.

Though I haven’t used it to build software if you want to create packages for many Linux distributions yourself OBS could be handy. I mention it for giving slower moving distributions an option that isn’t using another package manager (like snap or flatpak).

https://openbuildservice.org/

Some projects have guides for maintainers, but that’s only needed if it’s non obvious how to best build a package, do if things are different from the usual way in similar projects.

Guix

Without knowing more about the requirements Go is my default choice for CLI tooling. Self-contained executables for binary distribution, easy and fast builds for source distribution. First-class support for cross-compilation can be major too.

I am happy to see Go source code as a user too. I know that it will be straightforward and quick to build. Not a fan of magical self-updates and if that was the only option I’d probably pass on the tool. Easy to build source please. But I guess this greatly depends on your target audience.

A docker-format container does not (always) require docker desktop to be running. On a Linux host, you can use Podman which is daemonless, and supports user-invoked (unprivileged) containers too. Yes via docker desktop you get windows and mac coverage. Container UX is clunky for CLI apps, IMHO.

If you are willing to give up on the auto-update part, https://asdf-vm.com is worth considering. As requirements, it only requires bash, and basic unix tools like curl or git.

It entirely depends on what FOSS tool does and who are your target users. Personally I prefer docker containers, but I run Linux on my laptop. What I want from the distribution method: easy installation, easy upgrades, easy and clean uninstall. Docker solves all those problems. A single binary is OK too, although not as convenient.