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

  1. Download and install the installProxmox script:

repository signing key:

gitcurl clone-L https://github.com/automation-avenue/proxmox-on-raspberry.gitmirrors.apqa.cn/proxmox/debian/pveport.gpg cd| proxmox-on-raspberrysudo tee /usr/share/keyrings/pveport.gpg >/dev/null
  1. Make

    Add the scriptProxmox executable:

ARM64 repository to APT sources:

chmodecho +x"deb install.sh[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
  1. Run

    Refresh APT so it recognizes the installer:

new repository:

sudo ./install.shapt update

TheNow scriptinstall will:Proxmox and required packages:

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

During installation:

  • ConfigureChoose networkingLocal (bridges, static IP if needed)
  • Add PXVIRT repositories and GPG keys
  • Install Proxmox VE components adapted for ARM
  1. Waitonly for the scriptPostfix to finish. Reboot when prompted.

Access Proxmox Web Interface

  1. Find your Pi’s IP (via ip a or router).configuration
  2. OpenUse default mail settings if unsure

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

https://<pi-ipSTATIC_IP>:8006

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

with:

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

You install
Browsermay willalso warn aboutsee an insecure“invalid certificate.subscription” PXVIRTnotice, usesdismiss ait self-signedto certificate, which is normal

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.
  6. Regularly check for PXVIRT updates:
sudo apt update && sudo apt upgrade

Upgrade only when PXVIRT releases compatible updates. Avoid blindly using proxmox documentation for upgrades.

Back to top