Introduction
Most Proxmox tutorials about creating a VM assume you're installing Ubuntu, Debian, or Windows. FreeBSD barely gets mentioned, which is a little odd, because it runs beautifully under Proxmox VE. The KVM hypervisor that powers Proxmox has had solid FreeBSD support for years, and FreeBSD's own kernel has built-in VirtIO drivers, so you don't have to hunt down extra driver ISOs the way Windows users do.
If you've only ever installed Linux guests, FreeBSD will feel familiar in some ways and genuinely different in others. The installer looks nothing like Anaconda or Debian's installer. The filesystem layout uses different terms. And the default choice between UFS and ZFS trips up a lot of first-timers. None of that is a real obstacle once you know what you're looking at, and that's what this guide walks through, start to finish.
By the end you'll have a FreeBSD virtual machine running on Proxmox VE with the QEMU Guest Agent installed, a static-enough network setup, and a basic understanding of why FreeBSD admins do things a bit differently than their Linux counterparts.
What You Will Learn
- What FreeBSD is and why some homelab and server admins choose it over Linux
- How to download the right ISO and get a VM configured correctly in Proxmox VE
- How to get through the bsdinstall text installer without guessing
- The UFS vs ZFS decision, explained in plain terms
- How to install and enable the QEMU Guest Agent so Proxmox can see the VM's IP address and shut it down cleanly
- The errors people actually hit with this specific combination, and how to fix each one
What Is This Feature?
A virtual machine in Proxmox VE is a self-contained computer running inside your physical server. It gets its own virtual CPU, memory, disk, and network card, and the operating system inside it has no idea it isn't running on real hardware. Proxmox does this using KVM, a virtualization technology built into the Linux kernel, plus QEMU to emulate the hardware each VM sees.
FreeBSD is a free, open-source Unix-like operating system, separate from Linux even though people often lump the two together. It's not a Linux distribution — it has its own kernel, its own base system, and its own package manager called pkg. FreeBSD is what pfSense and OPNsense are built on, and it's popular for file servers, firewalls, and anywhere people want ZFS with rock-solid stability and a small, well-documented base system.
Inside Proxmox, a FreeBSD VM behaves like any other guest: it boots from an ISO, gets virtual disks and NICs, and can use snapshots, backups, and the QEMU Guest Agent just like a Linux or Windows VM.
Why Would You Use It?
Nobody switches to FreeBSD by accident. People usually land here for one of a few reasons. Some want native ZFS support that's been stable for over a decade, rather than a bolted-on module. Some are running jails (FreeBSD's lightweight containers, similar in spirit to LXC) and want that on top of Proxmox for extra isolation. Others are just curious after using pfSense or OPNsense and want to see what the OS underneath is actually like.
There's also a practical angle: FreeBSD has a genuinely small attack surface and a documented, predictable release cycle. If you're running something you want to touch as rarely as possible — a DNS resolver, an NFS server, a small mail relay — FreeBSD is a reasonable choice specifically because it doesn't change much between releases.
None of this means you should replace your Ubuntu VMs with FreeBSD. It means FreeBSD is worth having in your toolbox for the jobs it's actually good at.
Prerequisites
Before you start, make sure you have the following ready:
- A working Proxmox VE host (this guide was written against Proxmox VE 9.x, but the same steps work on 8.x)
- At least 20 GB of free storage and 2 GB of RAM to spare for the VM
- The FreeBSD 15.1-RELEASE (or 14.4-RELEASE, the older supported branch) amd64 disc1 ISO, downloaded from freebsd.org
- The ISO uploaded to a storage location Proxmox can see (Datacenter → your node → local storage → ISO Images → Upload)
- Basic comfort with a keyboard-driven, text-based installer — there's no mouse support in bsdinstall
If you've never uploaded an ISO to Proxmox before, it's a straightforward upload through the web UI, and it usually takes a couple of minutes on a typical home connection since the amd64 disc1 image is around 1.2 GB.
Step-by-Step Tutorial
1. Create the VM
Click Create VM in the top-right corner of the Proxmox web interface. On the General tab, give it a VM ID and a name like freebsd-test. Nothing special here yet.
2. OS tab
Select the storage where you uploaded the ISO, then pick the FreeBSD ISO from the dropdown. For Guest OS Type, choose Other — Proxmox doesn't have a dedicated FreeBSD entry in that list, and picking "Other" avoids Proxmox applying Linux-specific or Windows-specific defaults that don't fit.
3. System tab
Leave the BIOS as SeaBIOS unless you specifically need UEFI (FreeBSD supports both, but SeaBIOS is simpler for a first install). Check the box for Qemu Agent — this tells Proxmox to expect the guest agent later, even though you'll still need to install it manually inside the VM. For Display, pick Standard VGA rather than VirtIO-GPU. FreeBSD's VirtIO-GPU support is still catching up to Linux's, and Standard VGA avoids a black screen during install.
4. Disks tab
Set the bus to VirtIO SCSI single (or the older SCSI controller if you prefer — either works). FreeBSD's GENERIC kernel has built-in VirtIO block and SCSI drivers, so unlike Windows, there's no separate driver ISO to attach. Give it at least 20 GB — 8 GB technically boots, but you'll fill it fast once you start installing packages.
5. CPU and Memory tabs
Two cores and 2 GB of RAM is a comfortable starting point for a general-purpose FreeBSD VM. Set CPU type to host if your Proxmox cluster is uniform hardware; otherwise the default x86-64-v2-AES is fine.
6. Network tab
Set the model to VirtIO (paravirtualized). FreeBSD's vtnet driver is built into the GENERIC kernel, so it'll be detected automatically during install with no extra steps.
7. Boot the installer
Start the VM and open its console. You'll land on the FreeBSD boot loader menu — just let it count down, or press Enter. bsdinstall will launch and ask for a keymap. Most people can accept the default US layout.
8. Hostname and distribution sets
Set a hostname (something like freebsd-test.local is fine). On the distribution set screen, lib32 is worth keeping if you might run 32-bit software later; src and ports can be skipped for now — you can always fetch them afterward with git or portsnap if you decide you need them.
9. Partitioning
This is where bsdinstall diverges hardest from Linux installers. You'll be asked to choose Auto (ZFS), Auto (UFS), or manual partitioning. ZFS is FreeBSD's flagship filesystem — it supports snapshots, checksums on every block, and easy pool expansion. UFS is the older, simpler filesystem, closer in spirit to ext4. For a first FreeBSD VM, UFS is genuinely easier to reason about and recover from. If you already know ZFS from Proxmox's own storage options, Auto (ZFS) is a fine choice and gives you snapshots inside the guest as well as at the Proxmox level.
10. Disk selection and swap
With VirtIO SCSI single, your virtual disk shows up as da0. Select it, accept the default swap size (roughly matching your RAM is a safe default for a small VM), and confirm the destructive warning — this wipes the virtual disk, which is expected since it's brand new.
11. Root password, network, and time zone
Set a strong root password. The network step should auto-detect vtnet0 and offer DHCP — accept it unless you already know you need a static IP. Pick your time zone, then confirm the date and time bsdinstall detected.
12. Services
You'll be offered a checklist of services to enable at boot. At minimum, enable sshd so you can connect remotely later. ntpd is worth enabling too, for clock accuracy. You can leave powerd unchecked — it's meant for laptops managing CPU frequency, and it does nothing useful inside a VM.
13. Hardening and final user
The security hardening screen offers optional settings like disabling root SSH login syslogd network listening. For a homelab test VM, you can skip these and revisit them later once you're comfortable. Add a regular user account when prompted — don't skip this, since logging in as root over SSH is disabled by default good practice, and you'll want a normal account with wheel group membership to su when needed.
14. Finish and reboot
Exit the installer, let it reboot, and once it comes back up, detach the ISO from the VM's hardware tab so it doesn't try to boot the installer again.
15. Install the QEMU Guest Agent
Log in (console or SSH), switch to root with su, and run:
pkg install qemu-guest-agentThe first time you run pkg, it'll ask permission to bootstrap itself — answer yes. Once installed, enable and start the agent:
sysrc qemu_guest_agent_enable="YES"
service qemu-guest-agent startBack in the Proxmox web UI, the VM's Summary tab should now show its IP address within a few seconds, confirming the agent is talking to the host.
Commands Explained
| Command | What it does |
|---|---|
pkg install qemu-guest-agent | Installs FreeBSD's build of the QEMU Guest Agent, which lets Proxmox report the VM's IP, trigger clean shutdowns, and take filesystem-consistent snapshots. |
sysrc qemu_guest_agent_enable="YES" | FreeBSD's equivalent of enabling a systemd service — it writes the setting into /etc/rc.conf so the agent starts automatically on every boot. |
service qemu-guest-agent start | Starts the agent immediately, without waiting for the next reboot. |
freebsd-update fetch install | Downloads and applies official binary security patches for the base system — the FreeBSD equivalent of apt upgrade for the OS core. |
pkg update && pkg upgrade | Refreshes the package index and upgrades all installed third-party packages, similar to apt update && apt upgrade on Debian. |
Common Errors
Black screen right after the boot loader. This almost always means the Display device is set to VirtIO-GPU. Shut the VM down, switch Display back to Standard VGA in the Hardware tab, and boot again.
"mountroot>" prompt during boot after install. The kernel can't find the root filesystem, usually because the disk bus was changed after install (say, from VirtIO SCSI to VirtIO Block) — the device name changes from da0 to vtbd0 and the boot loader gets confused. Set the bus back to whatever you originally installed with.
No network after install. If DHCP didn't pick up during install, check ifconfig vtnet0 once logged in. If the interface exists but has no address, run dhclient vtnet0 manually and check that your Proxmox bridge (usually vmbr0) actually has DHCP available on it.
"pkg: Repository FreeBSD load error" or similar. This is almost always a DNS or connectivity problem, not a pkg problem. Confirm the VM can resolve names with host freebsd.org before troubleshooting pkg itself.
Guest agent installed but Proxmox still shows no IP. Double-check that Qemu Agent is actually checked in the VM's Options tab, not just installed inside the guest — both sides need to agree. A quick qm agent <vmid> ping from the Proxmox shell will tell you immediately whether the host can reach it.
Troubleshooting
If something goes wrong, start with the Proxmox task log for that VM — it shows the exact command Proxmox ran and often the underlying QEMU error text, which is more specific than what the console shows.
For install-time problems, open the VM's console and read the boot messages carefully; FreeBSD's dmesg-style boot output is verbose and usually names the exact device or driver that failed, which saves a lot of guessing.
If the VM boots but feels unusually slow, check that you're actually using VirtIO for both disk and network rather than the emulated defaults (IDE and Intel E1000). Those emulated devices work, but they're noticeably slower than VirtIO under load, and it's an easy setting to have missed during VM creation.
A stuck or hung install is often a memory issue — bsdinstall itself is light, but if you set memory too low (under 1 GB), certain distribution set downloads or extractions can stall without a clear error. Bump memory to 2 GB and retry if you see unexplained pauses.
Best Practices
Take a Proxmox snapshot or backup right after your first successful boot, before you install anything else. That gives you a known-good baseline to roll back to if a later package upgrade goes sideways.
Run freebsd-update fetch install soon after install and keep doing it periodically — this patches the base system, which pkg alone does not touch.
If you chose ZFS during partitioning, resist the urge to also enable Proxmox-level thin provisioning tricks on top of it right away. Nested copy-on-write filesystems can work, but they add complexity you don't need while you're still learning how the guest behaves.
Keep the ports and src trees off the VM unless you actually plan to compile things from source. They take up real disk space and aren't needed for typical package-based usage.
Frequently Asked Questions
Is FreeBSD harder to use than Linux?
Not harder, just different. The base system and package manager are separate concepts in FreeBSD, which trips people up at first, but the documentation (the FreeBSD Handbook) is unusually thorough.
Should I choose UFS or ZFS for a VM?
UFS if you want something simple and don't need snapshots inside the guest. ZFS if you're already comfortable with it or want in-guest snapshots on top of whatever Proxmox is already doing at the storage layer.
Does FreeBSD support cloud-init like the Linux VMs on this site?
There's a cloud-init port available (pkg install py-cloud-init), but it isn't preinstalled, so it's not as turnkey as Proxmox's built-in cloud-init support for Linux templates.
Can I run Docker containers on FreeBSD?
No — Docker relies on Linux kernel features. FreeBSD has its own container system called jails, which work differently and aren't Docker-compatible.
Is FreeBSD slower than Linux inside a VM?
In day-to-day use, no — with VirtIO drivers in place, disk and network throughput are close to what you'd see with a Linux guest on the same hardware.
Conclusion
A FreeBSD VM on Proxmox isn't exotic once you've done it once. The installer looks different, the terminology is different, and the package manager has a different name, but the underlying virtualization is the same KVM setup running your Linux and Windows guests. The parts that matter for a smooth install come down to a handful of specific choices: Guest OS Type set to Other, Display set to Standard VGA, VirtIO for disk and network, and the guest agent installed and enabled once you're in. Get those right and the rest of the process is just answering bsdinstall's prompts.
Whether you end up using FreeBSD for a DNS resolver, an NFS box, or just to see what pfSense is built on underneath, you now have a working guest to experiment with — and a reference for the specific errors that show up when Proxmox and FreeBSD don't quite agree on hardware defaults.