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”

You should have:

  • Python 3.12 or newer
  • uv for direct installation and source development; the guided installer can bootstrap it
  • a working terminal in the workspace where you want to run Bub

1. Install with the guided installer

Section titled “1. Install with the guided installer”

The standalone installer runs before Bub is installed. Download it first so you can inspect what it will execute:

curl -sSLO https://raw.githubusercontent.com/bubbuild/bub/main/install-bub.py
python3 install-bub.py

It first asks for one execution-surface preset:

PresetRequired pluginIntended use
chatnoneTerminal chat and one-shot commands.
lodybub-acp-serverACP sessions launched by Lody.

The next screen toggles optional plugins that are independent of the selected surface: web search, MCP tools, and semantic memory. A preset’s required plugin is not shown as a toggle; selecting lody always installs the ACP server.

For automation, CI, or a reproducible machine setup, skip all prompts:

python3 install-bub.py \
  --preset lody \
  --plugin web-search \
  --no-interactive

Repeat --plugin for curated options or --with REQUIREMENT for an additional Python package. Use --dry-run to print the complete uv command without changing the machine.

The installer delegates environment ownership to uv tool install. If uv is unavailable, it bootstraps uv in a temporary environment, then injects uv into Bub’s tool environment so bub install continues to work. The selected intent is recorded at ~/.bub/install.json (or $BUB_HOME/install.json); uv’s receipt remains the source of truth for the installed environment.

Verify that the binary is on PATH:

bub --help

To bypass the guided installer, install the released package directly:

uv tool install bub
# or
pip install bub

2. Install from source

Section titled “2. 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.

3. Pin Bub as a framework dependency

Section titled “3. 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.

4. Verify the install

Section titled “4. Verify the install”

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

uv run 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 builtin is missing or marked failed, re-run uv sync and check the error printed by the loader.

Next steps

Section titled “Next steps”