Installing Red on Raspberry Pi OS (Legacy) 10 Buster

We support hosting Red on computers running an armv7l version of this system.

You can read more about systems and processor architectures we support in our End-user Guarantees.

Note

While we do provide support and install instructions for running Red on Raspberry Pi OS (Legacy) 10 Buster, we highly recommend installing/upgrading to the new version - Raspberry Pi OS 11 Bullseye.

If you’re not sure what version you are using, you can check your version of Raspberry Pi OS by running:

lsb_release -a

If you’re running Bullseye already, read Installing Red on Raspberry Pi OS 11 Bullseye document instead.

If you’re using Buster, please consider upgrading to Bullseye if possible. You can read the post about Bullseye release from Raspberry Pi Foundation to learn how you can install/upgrade to the new version.

Warning

For safety reasons, DO NOT install Red with a root user. If you are unsure how to create a new user on Linux, see DigitalOcean’s tutorial: How To Create a New Sudo-enabled User.

Installing the pre-requirements

We recommend installing pyenv as a method of installing non-native versions of Python on Raspberry Pi OS. This guide will tell you how. First, run the following commands:

sudo apt update
sudo apt -y install cmake make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev libgdbm-dev uuid-dev python3-openssl git openjdk-17-jre-headless nano
CXX=/usr/bin/g++

Installing Python with pyenv

On distributions where Python 3.10 needs to be compiled from source, we recommend the use of pyenv. This simplifies the compilation process and has the added bonus of simplifying setting up Red in a virtual environment.

To install/update pyenv, run the following command:

command -v pyenv && pyenv update || curl https://pyenv.run | bash

After this command, you will see a warning about ‘pyenv’ not being in the load path. To address this, you should run these commands:

profile=$([ -n "$ZSH_VERSION" ] && echo ~/.zprofile || ([ -f ~/.bash_profile ] && echo ~/.bash_profile || echo ~/.profile))
rcfile=$([ -n "$ZSH_VERSION" ] && echo ~/.zshrc || echo ~/.bashrc)
printf '%s\n%s\n%s\n' 'export PYENV_ROOT="$HOME/.pyenv"' 'export PATH="$PYENV_ROOT/bin:$PATH"' "$([ -f "$profile" ] && cat "$profile")" > "$profile"
echo 'eval "$(pyenv init --path)"' >> "$profile"
echo 'eval "$(pyenv init -)"' >> "$rcfile"
echo 'eval "$(pyenv virtualenv-init -)"' >> "$rcfile"

Then log out and log back in and run the following command:

CONFIGURE_OPTS=--enable-optimizations pyenv install 3.10.13 -v

This may take a long time to complete, depending on your hardware. For some machines (such as Raspberry Pis and micro-tier VPSes), it may take over an hour; in this case, you may wish to remove the CONFIGURE_OPTS=--enable-optimizations part from the front of the command, which will drastically reduce the install time. However, be aware that this will make Python run about 10% slower.

After that is finished, run:

pyenv global 3.10.13

Pyenv is now installed and your system should be configured to run Python 3.10.

Creating a Virtual Environment

Tip

If you want to learn more about virtual environments, see page: About Virtual Environments

We require installing Red into a virtual environment. Don’t be scared, it’s very straightforward.

Using `pyenv virtualenv`

Using pyenv virtualenv saves you the headache of remembering where you installed your virtual environments. This option is only available if you installed Python with pyenv.

First, ensure your pyenv interpreter is set to python 3.8.1 or greater with the following command:

pyenv version

Now, create a virtual environment with the following command:

pyenv virtualenv <name>

Replace <name> with whatever you like. If you ever forget what you named it, you can always use the command pyenv versions to list all virtual environments.

Now activate your virtualenv with the following command:

pyenv shell <name>

Important

You must activate the virtual environment with the above command every time you open a new shell to run, install or update Red. You can check out other commands like pyenv local and pyenv global if you wish to keep the virtualenv activated all the time.

Installing Red

Choose one of the following commands to install Red.

To install without additional config backend support:

python -m pip install -U pip wheel
python -m pip install -U Red-DiscordBot

Or, to install with PostgreSQL support:

python -m pip install -U pip wheel
python -m pip install -U "Red-DiscordBot[postgres]"

Setting Up and Running Red

After installation, set up your instance with the following command:

redbot-setup

This will set the location where data will be stored, as well as your storage backend and the name of the instance (which will be used for running the bot).

Once done setting up the instance, run the following command to run Red:

redbot <your instance name>

It will walk through the initial setup, asking for your token and a prefix. You can find out how to obtain a token with this guide.

Tip

If it’s the first time you’re using Red, you should check our Getting started guide that will walk you through all essential information on how to interact with Red.