build your raspberry pi cluster

How to build your first Raspberry Pi cluster?

Do you have two or more Raspberry Pi at home?
Do you want to try putting them together to make a cluster?
If so, you’re at the right place. When I bought my second Raspberry Pi, I immediately wanted to build a cluster.

On Raspberry Pi, a cluster can be created by installing the same operating system, apps and libraries to all nodes. To run commands on all nodes, MPICH is the only app required. There is also a Python library to improve the possibilities: MPI4PY.

As this can be a complex topic for beginners, I’ll start with a little introduction on clusters in general.
Then I’ll explain what I have done and how you can do the same on your side.

By the way, if you don’t have a budget to afford a course for now (if you just got your Raspberry Pi stuff, I completely understand), you can join Skillshare for a free 14-day trial. It includes courses from the best teachers in many categories, including IT (Linux, programming, …) and Raspberry Pi. I highly recommend getting this offer now so that you can already learn a bunch of things in the next fortnight. I’m a fan of their services personally 🙂

Cluster presentation

What’s a cluster?

Basically, a cluster is a group of computers in a single entity.
The goal is to make them work together to improve the global performance.
All of the computers in a cluster work on the same task, reducing the time needed to finish it.

Don’t confuse computer clusters with load balancing.
In load balancing architecture, each computer is working on a different task to decrease the master node’s load.
In a cluster, we take advantage of the total power of the cluster to run a task in parallel.

Cluster examples

Computer clusters find their origins in the 60s and are still used today (at the same time as the first works on networking).


The first commercial computer cluster in the history is the Arcnet (see the image on the left).
Its goal was to connect groups of Datapoint 2200 computers.
It’s damn old in the computer history :).

At the time of writing this, the IBM Summit from the ORNL laboratory is the biggest supercomputer in the world.
With over 2 million CPU cores and 3000To of RAM, and always increasing, it will be tough to compete with.
Here is an illustration below if you want to know what it looks like:

summit computer cluster ibm
Summit from IBM (source:

Raspberry Pi application

Let’s go back to our more realistic dimensions with the adaptation of that definition on our Raspberry Pi.

As you know, the Raspberry Pi is not very powerful, but it’s cheap.
So, it’s the perfect device to build a cluster.

We can make a Raspberry Pi run tasks faster on 4 devices instead of only one, for a reasonable price.

In this tutorial, I’ll show you how to build your first Raspberry Pi cluster.
You can build a cluster with two nodes to start and add others later if needed.

Prepare your Raspberry Pi cluster

Make a plan

It’s always a good idea to think about what you are building.
I’m doing this exercise for you, with two Raspberry Pi:

  • A Raspberry Pi 4B 4G: the master node that will control everything
  • A Raspberry 3B+: the second node, to increase global performance

As the preparation phase can be pretty long (especially if you are using many nodes), I’ll prep the 4B only.
Then I’ll copy the SD card to another one, to get a Raspberry Pi 3B+ almost ready without having to do the whole preparation phase on the 3B+.
Finally, there are extra steps for both Raspberry Pi devices to connect them together and run the first script.

If you have more than one node to add, repeat the same process for each node.


To follow this tutorial, you’ll need:

  • 2 or more Raspberry Pi (any model, but I recommend the Raspberry Pi 4B)
  • 2 or more SD Cards (check my recommended product page if you need some)
  • A cheap 5-port gigabit switch to plug all Pi’s together
  • Power cables, or a power bank with 2 or more ports
  • A Network cable for each Pi (wireless is possible, but not optimal)
  • Optional: if you are serious about this project, this cluster case can be useful to stack Raspberry Pi and avoid a giant mess.
    The case will optimize your cabling, keep everything tidy, and also cool the nodes correctly. I highly recommend that kind of case if you’re keeping your cluster running frequently.

And for the software, I’ll explain everything in the following parts.

Download Your Essential Linux Commands Guide!
It's a free PDF guide containing every Raspberry Pi Linux command you should know!
Download now

Note: it’s okay if you use different sized SD cards, but you need to install the master on the smallest SD card.
Otherwise, you’ll have an issue when flashing a 64G image to a 16G SD card :).

Prepare the Master

The first step in my scenario is to make the installation on one Raspberry Pi and then duplicate to the others.
Start with your powerful Raspberry Pi.

Basic installation

Like most projects, we will start with the Raspbian installation.
Download the Raspbian Lite from the Raspberry Pi Foundation website: link here.
Raspbian Desktop is okay, but we don’t need a GUI for this project.

Install Raspbian and boot for the first time (if you don’t know how to install Raspbian on a Raspberry Pi, follow my guide and come back later).

Then you’ll need to follow these additional steps:

  • Change a few settings with Raspi-config:
    • Run Raspi-config:
      sudo raspi-config
    • Change the pi user password in “System options > Password”.
      We’ll enable SSH, and it isn’t a good idea to use the default password with SSH running.
    • Enable SSH in “Interface options > SSH”.
    • Change the host name in “System options > Host name”.
      Choose something clear, like “Master”
  • Update your system:
    • As always, start any project with an up-to-date system to avoid any issue.
      Update the repository sources:
      sudo apt update
    • Upgrade all packages:
      sudo apt upgrade
  • Reboot to apply all changes:
    sudo reboot

The basic installation is now complete, we can move to specific software for this project.

MPICH installation

What’s MPICH?

MPICH is the main tool we need to run a cluster.
MPICH is a free implementation from the MPI standard.
MPI stands for Message Passing Interface and its goal is to manage parallel computing architectures.

Join Our Community!

Connect, learn, and grow with other Raspberry Pi enthusiasts. Support RaspberryTips and enjoy an ad-free reading experience. Get exclusive monthly video tutorials and many other benefits.

Learn more

In short, this is what will allow us to run a script on several Raspberry Pi simultaneously.

MPICH installation

We are now ready to start the MPICH installation process.
If you want the latest version, you can download MPICH from the official website and compile it from the sources, but it’s also available in the Raspberry Pi OS repository.

So, this is the easiest way to install it:
sudo apt install mpich

Once done, test to ensure everything is working well.
To do this, run this command for example:
mpiexec -n 1 date

If you get the current date from the master, the MPI installation is completed.

Create a basic Python script

Ok, now we’ll create a basic Python script to test it with MPI.

  • Go to your home folder and create a script:
    cd /home/pi
    If you are not used to Nano, you can read my guide here for more details.
  • Paste this line inside (or whatever you want):
  • Make sure your script is working directly with Python:
    If you kept my script, this should display “Hello”
  • Then test it by running it on 4 threads with MPI:
    mpiexec -n 4 python
    As you can see, this should now display “Hello” four times, so we can also run a Python script 4 times, by using all the processor cores available.

This is nice, but we don’t use the cluster for the moment, it’s just a way to run a script on several threads.

MPI4PY installation

What’s MPI4PY

To go further with our cluster, we need a library that we can use in a script. The goal of this library is to have communication between all the nodes, to run efficiently our programs.

On Raspberry Pi, MPI can be used directly in Fortran and C scripts only.
But as the Raspberry Pi runs with Python, we’ll add Python capability to our cluster.

To do this, we need to install a Python library: MPI4PY.

MPI4PY prerequisites

MPI4PY installation process is easy as it’s available with pip (the Python package manager).
But you need to install some Raspberry Pi OS packages before anything else:
sudo apt install python-pip python-dev libopenmpi-dev

That’s it, move to the installation process.

MPI4PY installation

We can now install the MPI4PY library with pip:
sudo pip install mpi4py
It can take more or less time depending on your Raspberry Pi model. Be patient.

If this is working correctly, your master installation is ready.
MPI can now run Python scripts, and we can start the node’s preparation.

Duplicate the master

The next step is to duplicate the master’s SD card into other cards – one for each node.
To do this, we’ll create an image from the SD card and flash it on the other cards.

Download Your Essential Linux Commands Guide!
It's a free PDF guide containing every Raspberry Pi Linux command you should know!
Download now

If you are trying this with only two nodes, it might be faster to repeat the same procedure as on the master. In this case, you can skip this section.

Create the image

On Windows, you need a software like Win32DiskImager.
Click on the link, download and install it on your computer:

  • Start the program.
  • In the “Image file” field, choose a temporary directory and a filename such as “cluster_master.img”.
  • Then choose the Device letter corresponding to the SD card.
  • Finally, press the “Read” button to start the image creation.
    This process took about 15 minutes on my computer.
  • Once done, eject the master SD card and keep it safe.

On Linux, it should be something like:
sudo dd if=/dev/sdb > cluster_master.img
You need to make sure /dev/sdb is your SD card. You can easily find help for this command if needed (or use man dd to see all options).

Create SD Card for nodes

Once the image is ready, you need to create the SD card for each node of your cluster:

  • Insert the new SD card into your computer.
  • In Win32 Disk Imager, select the image filename and the device letter.
  • Click on “Write” to create the same SD card.

If you prefer, you can use Etcher to do this.
I typically use Etcher, but we are already in Win32 Disk Imager, so it’s the same.
As a reminder, you need to use an SD card larger than the first one.

flashing the cluster image

Once again, for Linux and macOS users, you can use the dd command if you don’t want to install Etcher.

At the end of this step, you have one SD card for each node you want to use.
All the SD cards contain the same image from the master we created before.

Nodes configuration

Start all Raspberry Pi

  • Insert an SD card in each Raspberry Pi you want to use.
  • Start them all.

If you want to use Wi-Fi for one or more nodes, there is an extra step.
For example, in my case I have a Raspberry Pi Zero, and it was easier for me to connect it to my Wi-Fi network.

  • Plug a screen and keyboard into the Raspberry Pi you want to use Wi-Fi on.
  • Use Raspi-config to configure the Wi-Fi:
    • Use the following command:
      sudo raspi-config
    • Go in System options > Wireless LAN.
    • Follow the wizard to select your network (country, SSID and pass phrase).

Find all IP addresses

Once all the Raspberry Pi are started and plugged in the network, we need to get all IP addresses to use it later:

  • Go back to the master node (directly or with SSH).
  • Install NMAP:
    sudo apt install nmap
    nmap is a free tool for network discovery (check the website here).
    We’ll use it to find all IP addresses.
  • Use this command to find all devices on your network with a host name containing “master” .
    For the moment, all the Raspberry Pi have the same host name:
    nmap -sP 192.168.1.* | grep master
    Change the network subnet if you are using another one.
  • You should get this kind of output:
    nmap scanning cluster ip
  • I now know my second node IP:

You should now have all the nodes’ IP.
If you don’t know the master one, you need to use this command:
sudo ifconfig

You’ll get something like this:


The IP address is on the second line after the “inet” keyword ( in this screenshot).
The last step is to note these IP addresses in a text file on your Master node:

  • Create a new file in your home folder:
    cd /home/pi
    nano nodes_ips
  • In this file, add a node IP on each line (and only the IP).
    For example:
  • That’s all for this part.

Change the nodes host names

We’ll now change the host name on the new nodes to have a different one for each:

  • From the master node, connect to the first one with SSH:
    ssh pi@
    Answer “yes” to the question and enter the pi password.
  • Go into Raspi-config:
    • Use this command to access the tool:
      sudo raspi-config
    • Go in System options > Host name.
    • Set a new host name for this node, for example “Node1”.
  • Exit raspi-config and exit this node with:

Repeat these steps for each node you want to add in the cluster.

Do the SSH keys exchange

The last step is to allow the master to connect to each node via SSH without password.
To do this, you need to create an SSH key on the master, transfer them to all nodes to allow it.

  • On the master, create the SSH key with:
    ssh-keygen -t rsa
    Accept the default values (default path and no password).
  • This tool generates two keys in the /home/pi/.ssh folder:
    • id_rsa: your private key, keep it here
    • the public key, you need to send it to peers you want to access without password
  • Transfer the public key to all nodes:
    scp /home/pi/.ssh/ pi@
    Do this for each node you want to use.
  • Then, go to each node and add the key to the authorized_keys file.
    This file contains all hosts allowed to access the system via SSH without password:
    ssh pi@
    cat >> .ssh/authorized_keys

    Do this for each node.
    If the folder doesn’t exist, just create it with:
    mkdir .ssh
  • Now, you should be able to connect each node without password.
    You can try it with:
    ssh pi@

That’s it, you cluster is ready. We’ll now test it.

Cluster usage

The cluster is now available, and we’ll use MPI to run commands simultaneously on each node.
As we already saw, MPI allows you to run basic commands and scripts through the cluster.

Basic command

The first thing we can try is to run the same command on each node.
Preferably something that doesn’t return the same thing :).

For example:
mpiexec -hostfile nodes_ips -n 8 hostname

nodes_ips is the file we created before with all IP addresses inside.
And “hostname” is the command we want to run on each node (more about the hostname command here).
8 is for the number of thread to start, in this case change it for the number of cores available in your cluster (Raspberry Pi 4B and 3B+ have 4 cores each, so I test with 8).

As a result, you’ll get one line for each node in the cluster, with all nodes host names.

Python script

Test script

If you followed this tutorial entirely, you should already have a script on the home folder.
You can test to run it on each node with the same command:

mpiexec -hostfile nodes_ips -n 8 python

This will display “Hello” two times, once for each node.
We are still not using MPI4PY, but we’ll get to this now.

A new script

Remember that after cloning all the SD cards, you need to have the new scripts on all nodes.
MPI simulates the execution of the script on each node, but it doesn’t copy the code automatically.

To do this, follow this short procedure:

  • Create the script on the master node.
  • Make sure it’s working as expected.
  • Then transfer this script on all nodes with scp:
    scp /home/pi/ pi@
    It’s important to have the same script on each node, and with the same path.
  • Then you can run your script with MPI as explained before.

Go further with Python

As I told you, we didn’t add MPI4PY just to run basic python scripts 4 times instead of one.
MPI4PY is a Python library you can include in your scripts to use specific functions in your cluster.

Here is a quick example:

#!/usr/bin/env python

from mpi4py import MPI

rank = comm.rank

if rank == 0:
    data = {'a':1,'b':2,'c':3}
    data = None

data = comm.bcast(data, root=0)
print 'rank',rank,data

The goal of this script is to send data from one thread or node to all the others.
In this script data is defined only for the first thread on the master (rank 0).
And then we sync this data with all running instances with the broadcast function (comm.bcast).

Here is the command to run to try this:
mpirun.openmpi -np <threads> -machinefile nodes_ips python

When you run this script, all nodes and ranks display the same message:

cluster python script

It just an example to show you that you can add more functions in your Python script to take advantage of your cluster.
I’m not an expert on this.
You can find more information here.

Download Your Essential Linux Commands Guide!
It's a free PDF guide containing every Raspberry Pi Linux command you should know!
Download now

Related questions

Can I add more nodes in my cluster now? You can add more nodes to your existing cluster at any time (that’s what they do with supercomputers). You just need to create a new SD card, follow the node configuration steps for the new node and add the new IP address in the nodes_ips file.

The IP addresses are changing every day, what can I do? Yes, it’s a problem. For the test I didn’t do this step, but if you want to keep your cluster you need to do this. Depending on your network, you can either set a reservation in your DHCP server (so each Pi will always get the same IP on boot). Or you can set manually a static IP address in your network configuration (I explain how to do this at the end of this article).

What kind of usage do I really need a cluster for? In this tutorial, it was mainly the technology and the installation process that interested me. Not the possibilities that are now available with this cluster. This is another topic and I can’t fit all in only one article. If you want to go further, you can find more projects about clusters on Hackaday

Download Your Essential Linux Commands Guide!
It's a free PDF guide containing every Raspberry Pi Linux command you should know!
Download now

🛠 This tutorial doesn't work anymore? Report the issue here, so that I can update it!

Reminder: Remember that all the members of my community get access to this website without ads, exclusive courses and much more. You can become part of this community for as little as $5 per month & get all the benefits immediately.


That’s it, you know how to build your Raspberry Pi cluster from two nodes to an infinity :).

I really liked writing this tutorial for you.
It’s interesting to have an overview on how supercomputers are working.
And the technology seems to be stable as I had no issues while creating my cluster (and it’s rare in computing ^^). I hope you’ll like that too.

By the way, you can check my related article here about what can be the real usage for a Raspberry Pi cluster.

If you have any questions or experiences to share, leave a comment in the community.
I would like to know what you do after this first steps in the supercomputer world 🙂

Whenever you’re ready, here are other ways I can help you:

The RaspberryTips Community: If you want to hang out with me and other Raspberry Pi fans, you can join the community. I share exclusive tutorials and behind-the-scenes content there. Premium members can also visit the website without ads.

Master your Raspberry Pi in 30 days: If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.

The Raspberry Pi Bootcamp: Understand everything about the Raspberry Pi, stop searching for help all the time, and finally enjoy completing your projects.

Master Python on Raspberry Pi: Create, understand, and improve any Python script for your Raspberry Pi. Learn the essentials step-by-step without losing time understanding useless concepts.

You can also find all my recommendations for tools and hardware on this page.

Similar Posts


  1. Thanks for the tutorial! I went ahead and setup an NFS share on the master and had the nodes mount it so I could drop scripts in there. It’s a fun exercise.

  2. Thank you for the concise information and instructions. My Raspberry Pi 3 master and 3 Pi Zeros cluster is working like a charm.

    Is there a limit to the number of nodes that you can add to a master controller Pi?
    If there is, how do big clusters work? Can you make a cluster of clusters?

    Thanx again.

  3. thanks man it really helped me since this is my first computer i own and you helped me built it

  4. Hi. I have set up a cluster of three.
    master is a debian 10 desktop (hostname win-home (don’t ask!)
    node i is a pi zero w
    node 2 is a Pi 3 model B all static.

    Testing the cluster listing hostname or the python give same result only two show.

    By switching the ip addresses arounf on the nodesips file I prove that the middle node is omitted.
    It fails completely to run (saying it can’t find the master node ip) unless the first ip is the master node. but if I switch the other two around it is always the middle one of the three that is missing and the commands always ‘hangs’ without finishing.

    If I use a multiple number of 3 ie 6 or 9 I get either 2 for each (total 4) or three for each (total 6).

    Testing each node separately works. Any ideas?

    p.s. At first I thought I might be having problems with multi-node processors but when I increased the count one by one I realised that it definately thought there were only three nodes.

  5. Cannot seem to find .ssh folder on any node besides the master node. As well, I do not seem to have an authorized_keys file on the master node, but a file called ‘known_hosts’. Any idea what to do?

  6. Hi

    interesting tutorial, this is about using some python scripts in your example to improve global performance

    but can we use this pi cluster to launch any single software (set on each node with the same raspbian image, like you did in your tutorial) ?

  7. Hi patrick, i try to build this cool cluster but het an error command not found at:
    sudo /opt/mpi-dl/mpich-3.3/configure –prefix=/opt/mpi
    I followed al the mentioned steps. Did i miss something?
    Greetings Melvin

    1. When you ran this command “tar zxvf mpich-3.3.tar.gz” you probably got errors. Need to do sudo tar zxvf mpich-3.3.tar.gz. I had the same problem btw.

  8. Do I have to flash SD cards or can i take the time to go through install steps for each node? I have other setup on my 2 worker nodes I would like to keep.

    My configuration will be
    master – 4b
    node 1 – 4b
    node 2 – 3b+

    1. I just repeated install on my worker node, so, my next question is everything worked except I am testing the commands which are not working

  9. I had to create the .ssh folder on my lzonepi4b2 which is the worker node to my master lzonepi4b1.
    I issue command :
    $/opt/mpi/bin/mpiexec -f nodesips -n 2 python
    and get:
    [mpiexec@lzonepi4b1] HYDU_parse_hostfile (/opt/mpi-dl/mpich-3.3/src/pm/hydra/utils/args/args.c:319): unable to open host file: nodesips
    [mpiexec@lzonepi4b1] mfile_fn (/opt/mpi-dl/mpich-3.3/src/pm/hydra/ui/mpich/utils.c:336): error parsing hostfile
    [mpiexec@lzonepi4b1] match_arg (/opt/mpi-dl/mpich-3.3/src/pm/hydra/utils/args/args.c:156):
    match handler returned error
    [mpiexec@lzonepi4b1] HYDU_parse_array (/opt/mpi-dl/mpich-3.3/src/pm/hydra/utils/args/args.c:178): argument matching returned error
    [mpiexec@lzonepi4b1] parse_args (/opt/mpi-dl/mpich-3.3/src/pm/hydra/ui/mpich/utils.c:1642): error parsing input array
    [mpiexec@lzonepi4b1] HYD_uii_mpx_get_parameters (/opt/mpi-dl/mpich-3.3/src/pm/hydra/ui/mpich/utils.c:1694): unable to parse user arguments
    [mpiexec@lzonepi4b1] main (/opt/mpi-dl/mpich-3.3/src/pm/hydra/ui/mpich/mpiexec.c:148): error parsing parameters

    What might have i done wrong somewhere?

  10. Nevermind, I mis typed nodesip file instead of using nodesips, sorry for my confusion.
    Working now.

  11. I have my Pi’s connected to my home network, but thought we wanted to use the ethernet switch, and power supplies to connect the pis together I didn’t see how you do that in this tutorial, is that at a different location?

  12. Hi i need help with mu cluster
    i followed your tutorial and when i came to the testing part(/opt/mpi/bin/mpiexec -f nodesips -n 2 python
    i got this message
    [proxy:0:0@Node1] HYDU_sock_connect (/opt/mpi-dl/mpich-3.3/src/pm/hydra/utils/sock/sock.c:145): unable to get host address for MasterNode (1)
    [proxy:0:0@Node1] main (/opt/mpi-dl/mpich-3.3/src/pm/hydra/pm/pmiserv/pmip.c:183): unable to connect to server MasterNode at port 46403 (check for firewalls!)

    i only have 1 node

    thank you and sorry for my bad English

  13. Hi i need help cluster
    I am creating a cluster as described, but it stop at some stage. it is “make: *** No targets specified and no makefile found. Stop.” But after setting it in the previous step, it says there is no makefile. What should I do?

  14. #1) Is there a way to duplicate the sd card using Raspbian? If not, can I duplicate the sd card using etcher?

    #2) I’m using two rpi 4 b’s 4gb for my cluster, can I connect their ethernet cables directly from the router instead of a gigbit switch?

    Thank you very much🙏

  15. I keep getting the following error:

    pi@raspberrypi:/opt/mpi-build $ sudo /opt/mpi-dl/mpich-3.3/configure – prefix=/opt/mpi
    configure: WARNING: you should use –build, –host, –target
    configure: WARNING: invalid host type: –
    Configuring MPICH version 3.3 with ‘–’ ‘prefix=/opt/mpi’ ‘build_alias=–’ ‘host_alias=–’ ‘target_alias=–’
    Running on system: Linux raspberrypi 5.10.11-v7l+ #1399 SMP Thu Jan 28 12:09:48 GMT 2021 armv7l GNU/Linux
    checking build system type… Invalid configuration `–’: machine `–’ not recognized
    configure: error: /bin/bash /opt/mpi-dl/mpich-3.3/confdb/config.sub – failed

    Any ideas?

Comments are closed.