bpkg.sh

What is bpkg?

bpkg is a package manager for Bash. It does for shell scripts what npm does for JavaScript, RubyGems for Ruby and pip for Python: it installs, updates and uninstalls reusable Bash packages, handling details such as execution permissions so you can run a tool after installation without extra setup.

The basic workflow is a single command. Running bpkg install term -g places the term package on /usr/local/bin, after which you can call term directly. Dropping the -g flag installs into a local deps/ directory instead, so a project can carry its own shell dependencies rather than relying on global state.

Where it fits

• Global installs suit general-purpose shell utilities you want available everywhere on a machine.
• Per-project installs suit scripts that belong to one repository, a build step, or a team workflow where versions should travel with the code.

Installing bpkg itself

The page lists three routes: a curl-based install script, installation through clibs (a C package manager), and cloning the repository and running its setup script. The choice mostly comes down to how much control you want over what lands on your system — the script is fastest, while a source clone is the most inspectable.

If you are deciding whether to adopt it, start with a local, non-global install of one small package in a scratch project. That shows you the deps/ layout and how a script is invoked before you commit to putting anything in /usr/local/bin.

How do I install bpkg on my system?

Install bpkg with the method that matches how you already manage software. The project offers three routes: a one-line install script, the C package manager clibs, and a manual source build.

Install script (fastest)

curl -sLo- https://get.bpkg.sh | bash

This is the path bpkg documents for most users. Piping a remote script into bash means you are trusting whatever the server returns at that moment, so if you want to verify it first, fetch the script, read it, then run it.

Via clibs

If you already use clibs for C packages:

clib install bpkg/bpkg

This suits you if clibs is already part of your toolchain and you would rather not add a separate install path.

From source

git clone https://github.com/bpkg/bpkg.git
cd bpkg
./setup.sh install

Choose this when you want to inspect the code, pin a specific revision, or install without relying on a remote script.

After installing, confirm it works and try the documented example:

bpkg install term -g
term

The -g flag installs globally (the docs cite /usr/local/bin), while omitting it installs into a deps/ directory for per-project use — for example bpkg install term followed by ./deps/term/term.sh. Use global installs for tools you want everywhere, and local installs when a project should carry its own pinned dependencies.

If bpkg is not found after installation, your shell's PATH likely does not include the install location; check where the installer placed the binary and add that directory to PATH. For background on the package manager itself, see bpkg home.

How does bpkg compare to other package managers like npm or pip?

bpkg is a package manager for Bash scripts, so it sits closer to npm or pip in concept than in scope. All three install and manage dependencies from a registry-like source, but bpkg targets shell tooling rather than a full programming-language ecosystem.

Where bpkg fits

• npm / pip: language-specific package managers for JavaScript and Python. They handle versioned dependencies, lockfiles, transitive trees, and large public registries.
• bpkg: installs Bash packages, handling execution permissions and placement. Its page shows both global installs (into /usr/local/bin) and per-project installs under a deps/ directory.
• Practical difference: npm and pip are usually the entry point for building an application; bpkg is more like a way to distribute small shell utilities and scripts consistently across machines.

When to choose which

The trade-off is breadth versus simplicity. npm and pip have deeper dependency resolution and ecosystem support; bpkg's advantage is that it speaks Bash natively, so you don't need a language runtime just to install a shell script.

A concrete scenario

If your team has a shared deploy.sh or log-parsing script, bpkg can install it globally so everyone runs the same version. If you're building a Node service, npm remains the right layer, and bpkg would only matter for any shell helpers you ship alongside it.

Next step

Check whether the tool you want already exists as a Bash package on bpkg; if it's a language library, stay with npm or pip. For shell-only utilities, compare installing via bpkg against simply cloning the repo.

How can I use bpkg to manage dependencies for a specific project?

Use bpkg install <package> without the -g flag. That installs the package into a deps/ directory inside your current project rather than into a system-wide location like /usr/local/bin.

From the page's own example:

# Installs `term` under the `deps/` directory
$ bpkg install term
$ ./deps/term/term.sh

So the project-local workflow is:

1. cd into your project root.
2. Run bpkg install <package> for each dependency you need.
3. Reference the installed script via its path under deps/, e.g. ./deps/term/term.sh, or add deps/ to your PATH for the duration of a script.

Project-local vs global

The trade-off is convenience versus isolation. Global installs give you a plain command name but can drift between machines and projects; local installs keep each project's dependencies self-contained, at the cost of longer invocation paths and needing to manage deps/ yourself (for example, whether to commit it or ignore it).

A practical next step

If you want the isolation without the long paths, add this near the top of your project's entry script:

export PATH="$PWD/deps:$PATH"

Then check whether your shell's startup files or any existing .gitignore should account for deps/. For installing bpkg itself, the page lists three routes: a curl-based install script, clib install bpkg/bpkg, or cloning the repository and running ./setup.sh install.

What types of packages can I install with bpkg, and where can I find them?

bpkg installs Bash packages — reusable shell scripts and command-line tools distributed as small "packages," not system packages from your OS repository. It handles the mechanics for you: placing files, setting execution permissions, and managing uninstalls.

Two ways to use a package

Where packages come from

The page's examples point at GitHub-hosted packages, such as the term package at github.com/bpkg/term. So in practice you find packages by browsing GitHub repositories that follow bpkg's package conventions, or by following links from a project's own README. The install script and source repository are also hosted on GitHub, which suggests the ecosystem is GitHub-centric rather than a central curated index.

Practical scenario

Suppose you want a small terminal helper available everywhere. Install it globally once, and it behaves like any other command. If instead you are writing a deploy script for one repository and want the helper versioned alongside the code, install it without -g and call it from deps/. That second approach keeps the dependency visible to collaborators who clone the repo.

Next step

Before installing anything globally, check the package's repository for what the script actually does and whether it expects specific shell features or external commands. For a project-local install, add deps/ to version control or document the install command in your README so others can reproduce it.

How do I uninstall bpkg or remove packages installed with it?

Uninstalling bpkg itself and removing packages it installed are two separate tasks. The page describes installing and uninstalling packages, but not a documented "uninstall bpkg" command, so treat the steps below as general shell advice rather than a feature list from the project.

Removing packages

• Global installs go to a system bin directory (the page's example shows /usr/local/bin). The page states bpkg handles installing/uninstalling, so the intended route is the package command itself — check bpkg help on your machine for the exact subcommand and flags before deleting anything by hand.
• Project-local installs live under a deps/ directory in the project (the page's example: ./deps/term/term.sh). Deleting that package's folder inside deps/ removes it from the project, and nothing else on your system is affected.
• If you must remove a global package manually, delete the script bpkg placed in the bin directory. First confirm the path, since a global install may target a different directory on your system.

Removing bpkg itself

• Installation was one of three routes: the install script, clib install bpkg/bpkg, or cloning the repository and running ./setup.sh install. There is no matching documented uninstall step, so removal depends on which route you used.
• Practical approach: locate the bpkg executable (command -v bpkg), inspect it to see whether it is a script or a symlink, and remove that file plus any bpkg library or data directory it references. If you installed via clibs, its own tooling is the cleaner path.
• If you cloned the source, the clone directory is self-contained; deleting it removes the source, but not any executable copied elsewhere by setup.sh.

Check before you delete

Run command -v bpkg and ls -l on the result to see exactly what exists and where. Keep a note of the paths before removing, so you can restore anything you did not intend to delete. For the project's own guidance and any updated removal instructions, see bpkg and the repository linked from that page.