Skip to main content

Installing Proxmox VE on a Raspberry Pi

Introduction

Proxmox VE (Virtual Environment) is a powerful, open-source virtualization platform typically designed for x86_64 servers. Official Proxmox does not support ARM architectures like the Raspberry Pi.

PXVIRT is a community-maintained fork of Proxmox VE for ARM64 devices, enabling you to run LXC containers and lightweight VMs on Raspberry Pi 4 or 5. While it won’t match the performance of a full server, it’s perfect for small homelabs, testing, or learning virtualization concepts.

This guide walks you through flashing the OS, preparing the Pi, installing PXVIRT, and accessing the web interface, with tips for safe updates and storage.

Installing Proxmox on a Raspberry Pi isn’t officially supported. PXVIRT makes it possible by providing ARM-compatible Proxmox packages. Performance is limited compared to x86 hardware, but you can still run containers and lightweight VMs.

This guide assumes:

  • Raspberry Pi 4 or 5 (4GB+ recommended)
  • MicroSD card or SSD storage
  • Wi-Fi or Ethernet network connection

Flash Raspberry Pi OS

  1. Download and install Raspberry Pi Imager: https://www.raspberrypi.com/software/
  2. Select Raspberry Pi OS (64-bit, Lite preferred). Lite is recommended if you don’t need a desktop environment.
  3. Choose your SD card or SSD as the target.
  4. Optionally enable SSH in Raspberry Pi Imager under “Advanced Options” for headless setup.
  5. Flash the OS and wait until complete.

Boot and Prepare Raspberry Pi

  1. Insert the SD card (or connect SSD via USB).
  2. Power on the Pi and SSH into it (default user: pi, password: raspberry) or use console.
  3. Connect to the internet (Ethernet or WiFi)
  4. Update the OS:
sudo apt update && sudo apt upgrade -y
sudo reboot
  1. Ensure your Pi is 64-bit:
uname -m

Should return aarch64

Set a Static IP or DHCP Reservation

Proxmox works best when the host IP does not change. You can achieve this in two ways.

Option A: DHCP Reservation (recommended)

  • Log in to your router or firewall
  • Create a DHCP reservation for the Raspberry Pi using its MAC address
  • Assign a fixed IP address

This keeps networking simple and avoids manual config changes on the Pi.

Option B: Static IP on the Raspberry Pi

If your Raspberry Pi is using NetworkManager, you can configure a static IP address using the nmcli command-line tool. This method avoids manual file editing and works well for Proxmox hosts.

List active network connections:

nmcli connection show

Note the name of the active Ethernet connection, usually something like Wired connection 1.

Configure the Static IP. Replace the values below to match your network.

sudo nmcli connection modify "Wired connection 1" \
  ipv4.method manual \
  ipv4.addresses your_IP/subnet \
  ipv4.gateway your_gateway \
  ipv4.dns your_dns

  # Example: 
  # sudo nmcli connection modify "Wired connection 1" \
  # ipv4.method manual \
  # ipv4.addresses 192.168.1.50/24 \
  # ipv4.gateway 192.168.1.1 \
  # ipv4.dns 192.168.1.1

Apply the Changes. Bring the connection down and back up:

sudo nmcli connection down "Wired connection 1"
sudo nmcli connection up "Wired connection 1"

Verify the IP Address

ip a

Confirm the Raspberry Pi now has the configured static IP.

Set Hostname

Set the hostname before installing Proxmox. Proxmox uses the hostname internally for certificates and cluster services.

  1. Set the hostname:
sudo hostnamectl set-hostname proxmox-pi
  1. Edit the hosts file:
sudo nano /etc/hosts

Ensure it contains:

127.0.0.1       localhost
127.0.1.1       proxmox-pi

Your raspberry pi will probably be managed by cloud-init. To make it persistent, edit the hostname in /boot/firmware/user-data.

sudo nano /boot/firmware/user-data

Install PXVIRT / Proxmox

Download and install the Proxmox repository signing key:

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

Add the Proxmox ARM64 repository to APT sources:

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

Refresh APT so it recognizes the new repository:

sudo apt update

Now install Proxmox and required packages:

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

During installation:

  • Choose Local only for the Postfix configuration
  • Use default mail settings if unsure

After installation, open a browser on your PC and go to:

https://<STATIC_IP>:8006

The web UI uses a self-signed SSL certificate, your browser will warn you. Proceed anyway.
Log in with:

  • Username: root
  • Password: the one you set earlier

You may also see an “invalid subscription” notice, dismiss it to continue.

Post-Install Notes and Recommendations

  1. Change default ports or enable UFW if exposed to a network.
  2. Raspberry Pi is experimental hardware for Proxmox, performance is limited compared to servers.
  3. Use lightweight VMs and containers.
  4. Keep the system updated cautiously, unsupported ARM packages may not follow official Proxmox release cadence. Upgrade only when PXVIRT releases compatible updates. Avoid blindly using proxmox documentation for upgrades.
  5. Optional: Connect storage (USB SSD, NFS, or SMB) for VMs/containers.
Back to top