Skip to content
Bub Bub Bub

Install Bub

This page explains how to install Bub for the three supported workflows: running the CLI, contributing to the framework from source, and depending on Bub from another package.

Before you begin

Section titled “Before you begin”

For the standalone installer, you only need:

  • curl on macOS and Linux, or PowerShell on Windows
  • a network connection that can reach bub.build, astral.sh, and PyPI

The installer bootstraps uv when needed. uv then installs a compatible Python automatically, so a system Python is not required.

1. Use the standalone installer

Section titled “1. Use the standalone installer”
curl -fsSL https://bub.build/install.sh | bash

The installer places uv and the bub executable in user-level directories. In an interactive terminal, it runs the colored, keyboard- and mouse-enabled preset picker through inquirer-textual, prompts for additional plugin dependencies, installs them with bub install, and then runs bub onboard. The UI dependency is provisioned ephemerally with uv run --with; it is not added to Bub. Set NO_COLOR to disable colored output.

Preset membership is defined only in the versioned preset catalog, so plugin bundles can evolve without changing the installers. recommended is the default bundle and minimal installs no optional plugins.

For automation, pass --preset explicitly. --dependency is repeatable and adds packages outside the selected preset (--plugin is an alias):

curl -fsSL https://bub.build/install.sh | bash -s -- \
  --preset recommended \
  --dependency extra-plugin

Non-interactive installs do not run onboarding; run bub onboard explicitly when configuration is required. The installer also asks uv to add its executable directory to your shell profile. Restart your shell after installation, then run bub --help.

You can inspect the scripts and the versioned preset catalog before running them at install.sh, install.ps1, and presets.json.

2. Install with an existing uv

Section titled “2. Install with an existing uv”

If uv is already available, the equivalent user-level installation is:

uv tool install "bub@latest"
uv tool update-shell

If you prefer pip, the equivalent is:

pip install bub

3. Install from source

Section titled “3. Install from source”

Use this path if you want to contribute to the framework or follow main:

git clone https://github.com/bubbuild/bub.git
cd bub
uv sync

uv sync creates a project-local virtual environment under .venv/ with every dev dependency. After sync, every example in these docs that uses uv run bub will work from the repo root.

4. Pin Bub as a framework dependency

Section titled “4. Pin Bub as a framework dependency”

Plugin and distribution authors should depend on Bub as a normal Python package. The plugin’s pyproject.toml should declare the dependency and register one entry point under the bub group:

[project]
name = "bub-my-plugin"
version = "0.1.0"
dependencies = ["bub>=0.1"]

[project.entry-points."bub"]
my-plugin = "bub_my_plugin.plugin:MyPlugin"

Bub discovers plugins through importlib.metadata.entry_points(group="bub"), so any package installed in the active environment that registers this entry point is loaded on framework startup.

5. Verify the install

Section titled “5. Verify the install”

The fastest way to confirm Bub loaded its built-in hooks is the bub hooks command:

bub hooks

You should see a summary that includes the builtin plugin and a list of hook implementations such as resolve_session, build_prompt, run_model_stream, render_outbound, and dispatch_outbound. If you installed from source, use uv run bub hooks instead. If builtin is missing or marked failed, reinstall Bub and check the error printed by the loader.

Next steps

Section titled “Next steps”