meta_package_manager.managers.bin module

meta_package_manager.managers.bin.DRY_RUN_UPDATES_FOUND = 3

Exit code bin update --dry-run uses to report that updates exist.

A dry run finding nothing exits 0, and finding something exits this instead, so neither is a failure. Anything else is.

class meta_package_manager.managers.bin.Bin[source]

Bases: PackageManager

Installer of binaries straight from GitHub releases and similar sources.

Caution

The package identifier is the absolute path of the installed binary, which is what list reports and what remove and update accept. That choice is forced rather than preferred: bin names a package differently depending on the verb. Installing takes a source spec (github.com/junegunn/fzf, a release-tag URL, goinstall://…, docker://…, a vendor host), while everything afterwards is keyed on the installed path. Handing a source spec back to remove does not resolve, and a bare basename resolves through $PATH first, so a managed binary shadowed by another copy on $PATH fails outright. The absolute path is the only identifier every non-installing operation accepts.

Note

That asymmetry is also why install is not implemented: no identifier list reports can be handed to it, so mpm could never install what it had just listed. Installing through bin stays a bin install <spec> the user runs themselves, and mpm reports and maintains the result.

No search: bin has no registry to search, only sources the user names. No sync: there is no index to refresh. bin prune is left alone too, since it drops configuration entries whose file has vanished rather than cleaning up packages.

Caution

A bin that has never been configured prompts for its download directory on every command, the listing included, and cannot be driven until someone answers once interactively. mpm sees that as a failed version probe and treats the manager as unavailable, which is the right outcome: an uninitialised bin has no inventory to report, and reporting zero packages would be a lie.

No escalation: bin installs into a directory it picked from $PATH for being writable, and never needs root.

Documentation: bin.

Initialize cli_errors list.

name: str = 'bin'

Return package manager’s common name.

Default value is based on class name.

homepage_url: str | None = 'https://github.com/marcosnils/bin'

Home page of the project, only used in documentation for reference.

platforms: frozenset[Platform] | Group | Platform | Iterable[Platform | Group] = frozenset({Platform(id='almalinux', name='AlmaLinux'), Platform(id='alpine', name='Alpine Linux'), Platform(id='altlinux', name='ALT Linux'), Platform(id='amzn', name='Amazon Linux'), Platform(id='android', name='Android'), Platform(id='arch', name='Arch Linux'), Platform(id='buildroot', name='Buildroot'), Platform(id='cachyos', name='CachyOS'), Platform(id='centos', name='CentOS'), Platform(id='chromeos', name='ChromeOS'), Platform(id='clearlinux', name='Clear Linux OS'), Platform(id='cloudlinux', name='CloudLinux OS'), Platform(id='debian', name='Debian'), Platform(id='endeavouros', name='EndeavourOS'), Platform(id='exherbo', name='Exherbo Linux'), Platform(id='fedora', name='Fedora'), Platform(id='generic_linux', name='Generic Linux'), Platform(id='gentoo', name='Gentoo Linux'), Platform(id='guix', name='Guix System'), Platform(id='ibm_powerkvm', name='IBM PowerKVM'), Platform(id='kali', name='Kali Linux'), Platform(id='kvmibm', name='KVM for IBM z Systems'), Platform(id='linuxmint', name='Linux Mint'), Platform(id='macos', name='macOS'), Platform(id='mageia', name='Mageia'), Platform(id='mandriva', name='Mandriva Linux'), Platform(id='manjaro', name='Manjaro Linux'), Platform(id='nixos', name='NixOS'), Platform(id='nobara', name='Nobara'), Platform(id='opensuse', name='openSUSE'), Platform(id='openwrt', name='OpenWrt'), Platform(id='oracle', name='Oracle Linux'), Platform(id='parallels', name='Parallels'), Platform(id='pidora', name='Pidora'), Platform(id='pikaos', name='PikaOS'), Platform(id='raspbian', name='Raspbian'), Platform(id='rhel', name='RedHat Enterprise Linux'), Platform(id='rocky', name='Rocky Linux'), Platform(id='scientific', name='Scientific Linux'), Platform(id='slackware', name='Slackware'), Platform(id='sles', name='SUSE Linux Enterprise Server'), Platform(id='slitaz', name='SliTaz GNU/Linux'), Platform(id='sourcemage', name='Source Mage GNU/Linux'), Platform(id='tuxedo', name='Tuxedo OS'), Platform(id='ubuntu', name='Ubuntu'), Platform(id='ultramarine', name='Ultramarine'), Platform(id='void', name='Void Linux'), Platform(id='windows', name='Windows'), Platform(id='wsl1', name='Windows Subsystem for Linux v1'), Platform(id='wsl2', name='Windows Subsystem for Linux v2'), Platform(id='xenserver', name='XenServer')})

List of platforms supported by the manager.

Allows for a mishmash of platforms and groups of platforms. Will be normalized into a frozenset of Platform instances at instantiation.

requirement: str | None = '>=0.27.0'

The release whose listing layout installed() reproduces: it reserves a leading column of the version field for the pin marker. The parser tolerates the older unreserved layout too, but the floor tracks what is verified.

extra_env: ClassVar = {'NO_COLOR': '1'}

Additional environment variables to add to the current context.

Automatically applied on each meta_package_manager.execution.CLIExecutor.run_cli() calls.

version_regexes: tuple[str, ...] = ('^bin version (?P<version>\\S+)',)

Search the version on the first line.

$ bin --version
bin version 0.29.1
commit: c24db4aced89c855062fe8e2907ae0deb3fb9f53
built at: 2026-08-02T13:37:10Z
built by: goreleaser

Four lines are printed and the version is the third word of the first, bare and without a v. There is no version subcommand.

cli_names: tuple[str, ...] = ('bin',)

List of CLI names the package manager is known as.

This list of recognized CLI names is ordered by priority. That way we can influence the search of the right binary.

..hint::

This was helpful in the case of the Python transition from 2.x to 3.x, where multiple versions of the same executable were named python or python3.

By default, this property’s value is derived from the manager’s ID (see the MetaPackageManager.__init__ method above).

id: str = 'bin'

Package manager’s ID.

Derived by defaults from the lower-cased class name in which underscores _ are replaced by dashes -.

This ID must be unique among all package manager definitions and lower-case, as they’re used as feature flags for the mpm CLI.

virtual: bool = False

Should we expose the package manager to the user?

Virtual package manager are just skeleton classes used to factorize code among managers of the same family.

property installed: Iterator[Package]

Fetch installed packages.

$ bin list
/home/user/.local/bin/fzf         v0.74.2  github.com/junegunn/fzf                                    OK
/home/user/.local/bin/rg          14.1.1   https://github.com/BurntSushi/ripgrep/releases/tag/14.1.1  OK
/home/user/.local/bin/terraform  *1.5.7    releases.hashicorp.com/terraform                           OK
property outdated: Iterator[Package]

Fetch outdated packages.

This is the operation that keeps bin a class rather than a definition, on two counts a fixed argument list cannot express.

Important

The report is written to stderr while stdout stays empty, and the run exits 3 when it finds anything to update. Both are deliberate on bin’s side: 0 means everything is current, so a zero exit is the empty answer here and only a code that is neither means the check itself failed. The entries the failing exit records are discarded, since this one is a result rather than an error.

$ bin update --dry-run

• /home/user/.local/bin/fzf v0.40.0 -> v0.74.2 (https://github.com/junegunn/fzf/releases/tag/v0.74.2)
• /home/user/.local/bin/gh v2.40.0 -> v2.97.0 (https://github.com/cli/cli/releases/tag/v2.97.0)
⨯ command failed                                   error=Updates found, exit (dry-run mode).

Note

A pinned binary is reported as pinned and skipped before its version is ever checked, so it never appears here. That matches the listing, which marks it with a *.

upgrade_all_cli()[source]

Generates the CLI to upgrade all packages.

--yes answers the single batch confirmation update asks before applying, and --continue-on-error keeps one failing binary from abandoning the rest of the run.

$ bin update --yes --continue-on-error
Return type:

tuple[str, ...]

upgrade_one_cli(package_id, version=None)[source]

Generates the CLI to upgrade the package provided as parameter.

Unlike some whole-system upgraders, naming a binary genuinely restricts the run to it.

$ bin update --yes --continue-on-error /home/user/.local/bin/fzf
Return type:

tuple[str, ...]

remove(package_id)[source]

Removes a package.

Warning

remove reports a name it could not resolve on stderr and still exits 0, so a zero exit here means the command ran, not that anything was removed. Confirm a removal by listing again.

$ bin remove /home/user/.local/bin/fzf
Return type:

str