This page is a "quick start" guide for installing BuildStream, with links to detailed instructions found in the reference documentation.

BuildStream is currently only supported natively on Linux. Users of Unix-like systems where OCI technology is available can still use BuildStream by following the Container Images guide.

Do you need BuildStream 2 or BuildStream 1?

There will soon be two major versions of BuildStream.

BuildStream 2 is currently in beta and due for final release in late 2022. We recommend all new projects to use the BuildStream 2 pre-releases.

BuildStream 1 is the "classic taste" version, stable and supported since 2018. No new feature development is planned for BuildStream 1.

If you want to build a specific project, check its project.conf file for the min-version setting. If the setting is 2.0 or above you need a BuildStream 2 pre-release, if the setting is not present then you need BuildStream 1.

If you want BuildStream 1 and 2 on the same host, you'll need to use a venv as they cannot share a single Python environment. See the "Installing in virtual environments" guide for instructions.

Installing BuildStream 2 pre-releases

If your distribution's 'unstable' stream has a buildstream package >= 1.95.2, use that. Repology has a useful table of package versions.

Otherwise, try installing from PyPI into your home directory:

pip3 install --user --pre BuildStream

Note that:

• Some host packages are required which Pip cannot provide, see the list in the reference manual's "Installing Dependencies" section.

• BuildStream 2 and its dependency grpc contain binary modules. The pip install command will work differently depending on whether prebuilt 'wheel' packages are available for your platform, and may fail if it can't build from source -- if this happens, follow the full build + install procedure linked below.

The full build + install procedure for BuildStream 2 is documented in the reference manual's "Installing" section.

Installing BuildStream 1

If your distribution has an up-to-date buildstream package == 1.6, use that. Repology has a useful table of package versions.

Otherwise, install from PyPI into your home directory:

pip3 install --user 'BuildStream == 1.*'

Some host packages are required beyond what Pip provides, see the list in the reference manual's "Installing dependencies" section

The full build + install procedure for BuildStream 1 is documented in the reference manual's "Installing from source" section.

Container Images

BuildStream can run inside container tools such as Docker, Podman, and Toolbx.

Prebuilt images containing bst are available at docker.io/buildstream/buildstream via the buildstream-docker-images project. Please read that project's USING.md file for usage instructions.

Note that the Docker --privileged flag is usually needed, as BuildStream runs element build commands in a nested container.

BuildStream Plugins

BuildStream is extensible via plugins written in Python. Projects should provide their own setup instructions they require specific plugins from the host.

Here are some common plugin sets:

Plugins for BuildStream 2:

• buildstream-plugins: documentation, PyPI package, GitHub project
• bst-plugins-container: documentation, PyPI package, GitLab project
• bst-plugins-experimental: documentation, PyPI package, GitLab project

Plugins for BuildStream 1:

• bst-external: documentation, PyPI package, GitLab project