Installing BuildStream on a Linux distro

Installing from distro packages

Arch Linux

Packages for Arch exist in AUR. Two different package versions are available:

The external plugins are available as well:


BuildStream is in the official Fedora repositories:

sudo dnf install buildstream

Optionally, install the buildstream-docs package to have the BuildStream documentation in Devhelp or GNOME Builder.

Installing from source

Until BuildStream is available in your distro, you will need to install it yourself from the git repository using python’s pip package manager.

BuildStream requires the following base system requirements:

  • python3 >= 3.5

  • libostree >= v2017.8 with introspection data

  • bubblewrap >= 0.1.2

  • fuse2

  • psutil python library (so you don’t have to install GCC and python-devel to build it yourself)

BuildStream also depends on the host tools for the Source plugins. Refer to the respective source plugin documentation for host tool requirements of specific plugins.

If you intend to push built artifacts to a remote artifact server, which requires special permissions, you will also need:

  • ssh

For the purpose of installing BuildStream while there are no distro packages, you will additionally need:

  • pip for python3 (only required for setup)

  • Python 3 development libraries and headers

  • git (to checkout buildstream)

Installing dependencies

Arch Linux

Install the dependencies with:

sudo pacman -S fuse2 ostree bubblewrap git \
               python python-pip python-gobject python-psutil lzip



With stretch, you first need to ensure that you have the backports repository setup as described here

By adding the following line to your sources.list:

deb stretch-backports main

And then running:

sudo apt-get update

At this point you should be able to get the system requirements with:

sudo apt-get install \
    fuse ostree gir1.2-ostree-1.0 bubblewrap git \
    python3 python3-pip python3-gi python3-psutil lzip
sudo apt-get install -t stretch-backports \
    gir1.2-ostree-1.0 ostree
Buster and newer

The following line should be enough to get the base system requirements installed:

sudo apt-get install \
    fuse ostree gir1.2-ostree-1.0 bubblewrap git \
    python3 python3-pip python3-gi python3-psutil lzip


For recent fedora systems, the following line should get you the system requirements you need:

dnf install -y fuse ostree bubblewrap git \
               python3 python3-pip python3-gobject python3-psutil lzip


Once you have the base system dependencies, you can clone the BuildStream git repository and install it as a regular user:

git clone
cd buildstream
git checkout <VERSION_TAG>
pip3 install --user -e .

This will install buildstream’s pure python dependencies into your user’s homedir in ~/.local and will run BuildStream directly from the git checkout directory.

Keep following the instructions below to ensure that the bst command is in your PATH and to enable bash completions for it.


We recommend the -e option because you can upgrade your installation by simply updating the checked out git repository.

If you want a full installation that is not linked to your git checkout, just omit the -e option from the above commands.

You can view available version tags here for example to install version 1.6.6 git checkout 1.6.6

You may require bst-external the install instructions can be found on the bst-external gitlab

Adjust PATH

Since BuildStream is now installed under your local user’s install directories, you need to ensure that PATH is adjusted.

A regular way to do this is to add the following line to the end of your ~/.bashrc:

export PATH="${PATH}:${HOME}/.local/bin"


You will have to restart your terminal in order for these changes to take effect.

Bash completions

Bash completions are supported by sourcing the buildstream/data/bst script found in the BuildStream repository. On many systems this script can be installed into a completions directory but when installing BuildStream without a package manager this is not an option.

To enable completions for an installation of BuildStream you installed yourself from git, just append the script verbatim to your ~/.bash_completion:

# BuildStream bash completion scriptlet.
# On systems which use the bash-completion module for
# completion discovery with bash, this can be installed at:
#   pkg-config --variable=completionsdir bash-completion
# If BuildStream is not installed system wide, you can
# simply source this script to enable completions or append
# this script to your ~/.bash_completion file.
_bst_completion() {
    local IFS=$'
    COMPREPLY=( $( env COMP_WORDS="${COMP_WORDS[*]}" \
                   COMP_CWORD=$COMP_CWORD \
                   _BST_COMPLETION=complete $1 ) )
    return 0

complete -F _bst_completion -o nospace bst;

Upgrading BuildStream

Assuming you have followed the default instructions above, all you need to do to upgrade BuildStream is to update your local git checkout:

cd /path/to/buildstream
git pull --rebase

If you did not specify the -e option at install time, you will need to cleanly reinstall BuildStream:

pip3 uninstall buildstream
cd /path/to/buildstream
git pull --rebase
pip3 install --user .