Skip to content
Bub Bub Bub

Install Bub

Choose the installation for the way you want to use Bub. Add Bub to a Python project with uv, or install the application with a setup script or uv.

Build your own agent

Section titled “Build your own agent”

Use Python 3.12 or later and add Bub to your project:

uv add bub
uv run python -c "from bub.core import Agent; print(Agent.__name__)"

If you are starting a new project, first run uv init --python 3.12 my-agent and cd my-agent.

The base installation includes the kernel’s dependencies: Republic, Pydantic, Loguru, and typing-extensions. The import check needs no model credentials. Continue with Build your own agent to configure a model in Python and run the first example.

Run the Bub application

Section titled “Run the Bub application”

Choose an installation method:

curl -fsSL https://bub.build/install.sh | bash

The shell and PowerShell scripts set up uv and Python 3.12 as needed, then install bub[app] into ~/.bub/.venv. They prompt you to choose a plugin preset and configure your model and channels.

When installation finishes, make sure the command directory is on your PATH, then check:

bub --help

Continue with Run Bub for the first time to start a conversation in your own workspace.

The base install and bub[app] contain the same package files. The extra changes which dependencies are installed. Without the application dependencies, the bub command exits with an instruction to install bub[app].

Use a virtual environment for application development

Section titled “Use a virtual environment for application development”

For plugin development or adding packages such as tracing exporters, use an environment you can activate:

uv venv --python 3.12
source .venv/bin/activate
uv pip install "bub[app]"
bub --help

In PowerShell, replace the activation command with .\.venv\Scripts\Activate.ps1. Run the application and install its extensions from this same environment. If your project already uses uv, you can instead add "bub[app]" with uv add and run its commands with uv run bub.

Declare a package dependency

Section titled “Declare a package dependency”

Add the dependency to the existing [project] table in your package’s pyproject.toml. For direct Agent use:

requires-python = ">=3.12"
dependencies = ["bub>=0.6.0"]

For a package that imports the builtin agent, Framework, plugins, skills, or channels:

dependencies = ["bub[app]>=0.6.0"]

Synchronize your project after editing its dependencies. Existing applications should follow Upgrade to 0.6.0 when updating the dependency.

Contribute from source

Section titled “Contribute from source”

Clone the repository to work on Bub itself:

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

uv sync installs the development group, including application dependencies and Python check tools. You can then use uv run bub and the repository’s test commands.