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 — used by every example below
  • a working terminal in the workspace where you want to run Bub

1. Install from PyPI

Section titled “1. Install from PyPI”

For most operators, install the released package into a virtual environment managed by uv:

uv tool install bub

Verify the binary is on PATH:

bub --help

If you prefer pip, the equivalent is:

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”