How to Install Proxmox on the Raspberry Pi

In this tutorial, you will learn how to install the Proxmox Virtual Environment on the Raspberry Pi.

Proxmox Virtual Environment is an open-source virtualization platform that has an incredibly powerful and useful web interface.

You can easily manage virtual machines and containers on your Raspberry Pi using the built-in web interface.

This web interface even allows you to set up software-defined storage, network, and more. If you want to run VMs on your Raspberry Pi, Proxmox is one of the go-to solutions.

Thanks to recent advancements in Proxmox VE, it has support for ARM systems. The downside is that the team does not provide any builds for ARM64. Luckily, we can use a third-party package repository that has everything pre-compiled for us.

The version of the Proxmox Virtual Environment that we will be installing in this guide is Proxmox 8. This version of Proxmox has been built for the Bookworm operating system, meaning we can use Proxmox on a Raspberry Pi 5.

Remember that while running virtual machines on your Raspberry Pi, avoid using anything too heavy. The Raspberry Pi’s aren’t the strongest machines but should be able to handle a few little VMs.

Please note that for this tutorial to work, you must be running the 64-bit version of Raspberry Pi OS Lite Bookworm. Using other operating systems is not guaranteed to work and likely cause issues.

Equipment

Below is a list of the equipment we used when setting up the Proxmox Virtual Environment on our Raspberry Pi.

Optional

Raspberry Pi Case ( Amazon )
USB Mouse ( Amazon )
USB Keyboard ( Amazon )
HDMI Cable ( Amazon )
Monitor ( Amazon )

This tutorial was last tested on a Raspberry Pi 5 running the latest version of Raspberry Pi OS Lite Bookworm 64-bit.

Installing Proxmox on the Raspberry Pi

Over the following sections, we will walk you through installing the Promox virtual environment on your Raspberry Pi.

We highly recommend that you follow these steps using a clean installation of Raspberry Pi OS Lite. In particular, you should be using the 64-bit Bookworm version.

A non-clean version of the operating system may cause the Proxmox installation process to break.

Preparing your Raspberry Pi for Proxmox

1. Our first task before installing Proxmox onto the Raspberry Pi is to update the package list cache and upgrade any out-of-date packages.

You can perform both tasks by using the following two commands within the terminal.

sudo apt update
sudo apt upgrade

2. Your next step is to ensure that curl is installed on your Pi. We will be using curl to grab the GPG key for the Proxmox ports repository that we will be relying on.

You can install this package by using the following command within the terminal.

sudo apt install curl

3. Before proceeding with this tutorial, you must set up your Raspberry Pi to use a static IP address.

The best way to do this is using DHCP reservation in your router. However, we have a guide that shows you how to do this through your Raspberry Pi if you don’t have access to your router.

Modifying your Hosts File for Proxmox

4. After setting up a static IP address, we must now edit the hosts file. Proxmox expects your hostname to point to the IP address of your Raspberry Pi.

You can begin editing the hosts file on the Raspberry Pi using the nano text editor by running the following command.

sudo nano /etc/hosts

5. With the hosts file open, you should see a line similar to the one below. Our hostname is set to the default “raspberrypi“, but yours might differ.

127.0.0.1            raspberrypi

After finding this line, you will want to replace “127.0.0.1” with the local IP address of your Raspberry Pi.

In our case, our Pi’s IP is “192.168.0.32” so we changed the line to look like the following.

192.168.0.32            raspberrypi

6. After making these changes, save and quit by pressing CTRL + X, Y, and then the ENTER key.

7. To verify that our changes are working, we can use the hostname command to output the IP address of our Raspberry Pi.

hostname --ip-address

If you have configured everything properly, the static IP of your Pi should be returned.

192.168.0.32

Set a Password for the root User

8. The next thing we must do to use Proxmox on our Raspberry Pi is set a password for the “root” user. If we don’t set a password for this user we will be unable to login through the Proxmox web interface.

You can set a password for the root user using the command below within the terminal.

sudo passwd root

9. To set a password, you must enter it twice, as shown below. We recommend that you set a strong password for this.

A password manager such as NordPass (Affiliate Link) makes generating and storing strong passwords significantly easier.

New password:
Retype new password:

Adding the Proxmox Port Repository to your Raspberry Pi

10. We are finally at the stage where we can begin adding the Proxmox Ports repository to our Raspberry Pi. This repository is managed by a third-party but allows us to install versions compiled for the Raspberry Pi’s hardware.

Our first step in this process is to add the GPG key for the repository. This key helps verify that the packages legitimately come from the Proxmox ports repository.

curl -L https://mirrors.apqa.cn/proxmox/debian/pveport.gpg | sudo tee /usr/share/keyrings/pveport.gpg >/dev/null

11. With the GPG key added, we can now add the repository itself to our sources list.

Use the command below to save the repository link into a file called “pveport.list“.

echo "deb [arch=arm64 signed-by=/usr/share/keyrings/pveport.gpg] https://mirrors.apqa.cn/proxmox/debian/pve bookworm port" | sudo tee  /etc/apt/sources.list.d/pveport.list

12. Since we made changes to the sources list, we must update the package list cache again by running the following command.

If we don’t do this, the package manager will be unaware of the repository we just added.

sudo apt update

Preparing your Pi’s Network for Proxmox

These next couple of sections will ensure that your network will continue to function once Proxmox has been installed. Without these steps you will lose network connection later.

Installing ifupdown2

13. With everything in place, we can finally begin installing Proxmox on the Raspberry Pi.

The first package that must be installed on our system is “ifupdown2“. Proxmox uses this package to handle the network.

sudo apt install ifupdown2

Please note, if you run into an error that says the following, there are a couple of extra

If you see the following error message when installing “ifupdown2” then you will need to follow steps “a” and “b” below. Otherwise, skip straight to step 14.

error: Another instance of this program is already running.

a. To work around the “already running” error, we will need to do some workaround steps to get ifupdown2 running.

This step involves deleting a temporary file that the ifupdown2 package is searching for during installation

sudo rm /tmp/.ifupdown2-first-install

b. With the temporary file removed, we need to re-run the install process for ifupdown2 again by using the following command.

This will ensure that the final setup steps are properly executed.

sudo apt install ifupdown2

Modifying Your Network Interfaces

14. Our next step is to make some adjustments to the interfaces file. If we don’t make these changes, Proxmox will break when your Raspberry Pi restarts.

With these changes we will be setting our “eth0” interface to manual and create a new network interface that will bridge your connections and be used by your virtual machines.

You can begin to write this file by using the following command.

sudo nano /etc/network/interfaces

15. Within this file, you will want to add the following lines to the bottom of the file. There is a chance some of these interfaces are automatically specified, delete them and replace them with the values we have specified here

While filling out this file you must replace two values.

<IPADDRESS>: Change this placeholder with the IP address of your Raspberry Pi. This must be the local IP that it is accessible on.
<GATEWAY>: Replace this placeholder with the IP address of your gateway. Typically this will be the IP of your router.

In a lot of cases this will actually be “192.168.0.1“.

auto lo
  iface lo inet loopback

auto eth0
  iface eth0 inet manual

auto vmbr0
iface vmbr0 inet manual
        address <IPADDRESS>
        gateway <GATEWAY>
        netmask 255.255.255.0
        bridge-ports eth0
        bridge-stp off
        bridge-fd 0

16. Once you have filled out this file, save and quit by pressing CTRL + X, Y, and then ENTER.

17. To ensure these network changes are working, restart your Raspberry Pi by running the following command in the terminal.

sudo reboot

Installing Proxmox to the Raspberry Pi from the Repository

18. Finally, you can install Proxmox VE and a few required packages by typing the following command in the terminal.

This installation process can take a few minutes, so be prepared to wait a few minutes. Additionally, there are a few prompts you will have to go through during installation.

sudo apt install proxmox-ve postfix open-iscsi pve-edk2-firmware-aarch64

19. During installation, you will be asked to configure Postfix. You can navigate this menu using the ARROW keys to move and ENTER to select.

If you are unsure what you are doing here, select the “Local only” option.

20. Next, you will be asked to set the mail name for Postfix to utilize (1.).

Again, if you don’t know what you are doing here, leave the default name and press ENTER to continue (2.).

Accessing the Proxmox Web Interface

21. Once Proxmox finishes installing to your Raspberry Pi, it should be safe to access its web interface.

All you need to access the web interface is the IP address of your Raspberry Pi.

hostname -I

22. With your IP address in hand, you will want to go to the following address in your favorite web browser. Please note if you can’t connect, try restarting your Raspberry Pi and waiting a few minutes.

Ensure that you replace “<IPADDRESS>” with the IP of your Raspberry Pi.

https://<IPADDRESS>:8006

23. With the Proxmox web interface now open in your web browser, you must log in to your account.

Start by typing in the username as “root” and then use the password you set earlier for this user (1.).

Once you have filled in your information, click the “Login” button (2.).

24. You should now have access to the Proxmox web interface.

You can begin to set up new VMs through this interface as well as configure Proxmox VE itself.

Conclusion

Hopefully, at this stage in the tutorial, you will now have Proxmox VE installed on your Raspberry Pi.

You can utilize this tool to set up and manage virtual machines on your Pi. It is a powerful hypervisor, especially for those dealing with multiple virtual machines.

Please feel free to leave a comment below if you have run into any issues with getting this software to work on your device.

If you found this tutorial to be helpful, we highly recommend checking out our many other Raspberry Pi projects.

21 Comments

Sergio on December 12, 2024 at 8:52 pm

Hi, thanks for the tutorial! I think it’s missing one last step, how to resize the partition in order to have some space to use for a local-lvm partition.

Rudi Klein on December 8, 2024 at 8:23 am

A very readable, comprehensive tutorial. Great stuff!

Luis Alvarez on December 2, 2024 at 6:31 pm

If you use address in /etc/network/interfaces, remember use slash with the size of your network, otherwise you cannot access to your proxmox server because it’s going to use /32.

address 10.0.0.10/24
gateway 10.0.0.1

Martin on December 2, 2024 at 5:28 am

Dear Emmet,
thank you for your excellent Tutorial as well! I had to do it twice and that`s the way you learn about things…
I had some problems with the ifupdown2 too and there was no /tmp/.ifupdown2-first-install file found. I solved it with –reinstall…
Than I had problems with the “interfaces” file: I could not connect via ssh after reboot.
Maybe the “netmask 255.255.255.0” is missing? Or it was the second reboot…don’t know. Now everything seem to work fine.
But Thank you anyway very much!
Martin

tony on November 19, 2024 at 12:25 am
excellent tutorial, thanks for expending the effort to write it up.
however, i have recently followed this and found that ifupdown2 doesnt install correctly and makes the network fail on reboot (post doing the changes to the hostfile etc).
```
-----
error: Another instance of this program is already running.
dpkg: error processing package ifupdown2 (--configure):
------
```
im not sure how to get around this or resolve it. looks like a number of other people on forums have similar issues installing ifupdown2.
some say to apt fix-broken-packages, some delete ifupdown first-install files, some install ifupdown2 on different kernals and some install ifupdown2 from a different repository (proxmox repo), but on rasp pi5 lite OS (64) im a bit stuck. has anyone else run into this with thier pi5 proxmox install?

1. Emmet on November 19, 2024 at 1:47 am
  
  Editor
  Hi Tony,
  
  Sorry to see that you have been having issues with installing Promox. I have added some workaround steps to this guide that should hopefully resolve this issue.
  
  For some reason, ifupdown2 seems to think the service has already started when it hasn’t. Deleting a temporary file and re-running the install command.
  
  sudo rm /tmp/.ifupdown2-first-install sudo apt install ifupdown2
  
  Please let me know if it resolves your issues. I re-ran the tutorial a couple of times and the workaround seems to be working.
  
  Kind regards,
  Emmet
  
deepsys on October 13, 2024 at 9:08 pm

Wonderful documentation and nice website!!

Thanks a lot from germany 🙂

save on September 21, 2024 at 2:52 am

Great: this guide is clear and useful

Joe on September 17, 2024 at 5:48 am

Thank you so much for this

Jason Best on September 6, 2024 at 8:12 pm

I don’t know if anyone else has had this problem but any changes made to the network interface doesn’t work and access to the proxmox (raspberry pi) is lost. Given that Proxmox uses ifupdown2 to write the network config to the /etc/network/interfaces file, it seems to be incompatible with the raspberry pi. If anyone has this problem and found the solution please reply.

1. Wolfy on September 19, 2024 at 10:20 pm
  
  You are using bookworm right? that’s the issue with this proxmox on the rpi, I found when i altered the network from static to DHCP it would break as well, like everybody else, but i left it at static for the network settings on the CT and VM and I used the crontab to run on startup the following…. works like a treat… any other version aka bullseye fedora etc was fine without having to do this..
  crontab -e
  @reboot /usr/bin/systemctl restart systemd-networkd
  then it will pick up on the DHCP by itself….
  
2. Luis Alvarez on December 2, 2024 at 6:27 pm
  
  Me too, if you use static IP with interfaces file, you must setup /24 or whatever you are using in address.
  
Wolfy on August 12, 2024 at 8:03 pm

Well documented and thx for your efforts… cheers….

Flynn on August 4, 2024 at 10:24 pm

Thanks

John Smith on July 19, 2024 at 4:32 am

I had to change echo “deb [deb=arm64 signed-by=/usr/share/keyrings/pveport.gpg] https://mirrors.apqa.cn/proxmox/debian/pve bookworm port” | sudo tee /etc/apt/sources.list.d/pveport.list

to:
echo “deb [arch=arm64 signed-by=/usr/share/keyrings/pveport.gpg] https://mirrors.apqa.cn/proxmox/debian/pve bookworm port” | sudo tee /etc/apt/sources.list.d/pveport.list
for this to work on my pi5

1. Emmet on July 19, 2024 at 8:59 am
  
  Editor
  
  Hi John,
  
  Thank you for posting about that. I had tested this several times and never realised that I had typed in “dev” instead of “arch”.
  
  Much appreciated.
  
  Kind regards,
  Emmet
  
Declan on May 23, 2024 at 10:08 am

Boom….it works. Thanks very much Emmet. Great instructions. Clear, consise and best of all work!!! Thank you…thank you….thank you

1. Declan on May 23, 2024 at 11:39 pm
  
  Can i suggest a follow up to the series…..containers v vm’s…..and how to for both
  
Tu on April 25, 2024 at 10:09 am

Thank you Emmet, what a great tutorial, both clear and detail enough.

Oadslug on February 9, 2024 at 2:18 am

Great tutorial. Thank you. Proxmox up and running on RPi5 on NVMe!

One question. During install process I was asked by installer if I wanted to replace source list with one provided by package developer. I answered no, but in retrospect, this may have been a mistake. Was it? I have since run a post-install script I found elsewhere to fix resource lists, which seems to be working. But any advice here for next go around. Thx.

1. Emmet on February 9, 2024 at 8:47 pm
  
  Editor
  
  Hi Oadslug,
  
  You are safe not to override the source list with the provided one. They should be essentially the same thing and both refence the official Promox repository.
  
  King regards,
  Emmet