Introduction
You've got Proxmox VE running, you're happy with it, and now you want a proper NAS on top of it instead of a folder of shares hacked together on the host. TrueNAS Scale is the obvious answer for a lot of homelabbers, and the good news is you don't need a second box to run it. You can install it as a virtual machine right inside Proxmox, alongside whatever else you're already running.
The catch is that a NAS VM isn't quite like installing Ubuntu or Windows. Get the disk setup wrong and you'll end up with a "NAS" that can't see disk health, can't be trusted with SMART data, and silently defeats half the reason you wanted ZFS in the first place. This guide walks through building the VM the way people who've done this a hundred times actually do it — current as of TrueNAS Scale 25.10.4 "Goldeye" and Proxmox VE 9.2.
None of this is exotic. It's a handful of settings that matter, one decision about how your disks get to the VM, and then TrueNAS's own installer takes over from there.
What You Will Learn
- What TrueNAS Scale actually is and how it differs from plain Proxmox storage
- Why disk passthrough matters more here than in almost any other VM you'll build
- How to create a VM with settings that won't bite you later
- How to pass real disks through to TrueNAS, two different ways
- How to install TrueNAS and get through the first-boot wizard
- The errors people hit most often, and how to actually fix them
What Is This Feature?
TrueNAS Scale is a free, Debian-based operating system built around ZFS, a filesystem that checksums every block it writes and can tell you the moment a disk starts silently corrupting data — something ordinary filesystems like ext4 or NTFS simply can't do. On top of ZFS, TrueNAS adds a web interface for creating storage pools, sharing files over SMB and NFS, running scheduled snapshots, and installing a handful of apps.
It's the successor to what used to be a separate FreeBSD-based product (TrueNAS CORE). Scale is the actively developed line now, and it's what you'd download today from truenas.com.
Running it as a VM inside Proxmox instead of on bare metal means one physical machine can host your NAS, your VMs, and your containers at the same time. That's the whole appeal for a homelab — you're not buying a second server just to get file shares.
Why Would You Use It?
If all you need is a shared folder for two or three VMs, honestly, an LXC container running Samba will do that with a fraction of the RAM. TrueNAS earns its keep when you actually want the features around the storage: automated snapshots you can browse and roll back from the Windows "previous versions" tab, replication to a second machine, disk health monitoring, and a UI that doesn't require memorizing zfs and zpool flags.
The tradeoff is RAM and a bit of setup complexity, mainly around getting real disks in front of TrueNAS instead of virtual ones. Once that part's done, day-to-day it's just a NAS that happens to live in a VM. Most people who try this stop thinking about the "virtualized" part within a week.
Prerequisites
Before you start, make sure you have:
- Proxmox VE 8.x or 9.x installed and reachable through its web interface
- At least 16 GB of RAM in the host, with 8 GB or more you're comfortable dedicating to the TrueNAS VM (ZFS likes RAM for caching — this isn't a "2 GB and it'll be fine" kind of OS)
- One or more physical disks free for TrueNAS to manage — ideally not the same disk Proxmox itself boots from
- The TrueNAS Scale ISO downloaded from truenas.com (25.10.4 "Goldeye" at the time of writing)
- Root or a user with sudo access on the Proxmox host, for anything you need to do at the shell
A quick note on hardware: if your disks hang off an HBA card (a dedicated disk controller, common in old server chassis) rather than your motherboard's own SATA ports, you're in a good spot — passing through the whole controller is the cleanest option and we'll cover it below.
Step-by-Step Tutorial
Step 1: Upload the ISO
In the Proxmox web UI, click your storage (usually local) in the left tree, open the ISO Images tab, and click Upload. Pick the TrueNAS Scale ISO you downloaded. It's a little over a gigabyte, so on a home connection this takes a few minutes.
Step 2: Create the VM
Click Create VM in the top right. Work through the wizard with these settings:
- General: give it a name like truenas. Doesn't matter functionally, just make it recognizable.
- OS: select the ISO you just uploaded. Guest OS type: Linux, version 6.x - 2.6 Kernel (this covers modern Debian-based systems fine).
- System: set Machine to
q35and BIOS to OVMF (UEFI). Add an EFI disk when prompted — TrueNAS boots more reliably under UEFI than SeaBIOS in most people's experience. Leave the Qemu Agent box checked; TrueNAS Scale ships with agent support built in, so you don't need to install anything extra inside the guest for it to work. - Disks: delete or ignore the default disk for now — you'll size the real boot disk here. 32 GB is plenty for the TrueNAS OS itself; it doesn't store your data. Use VirtIO SCSI as the controller.
- CPU: 2-4 cores is fine for a home NAS. Set Type to
hostso the VM sees your CPU's real feature set instead of a generic emulated one. - Memory: at least 8192 MB. Turn off the memory ballooning device — untick "Ballooning Device" or set min equal to max. ZFS wants a stable, dedicated chunk of RAM for its cache (called the ARC), and ballooning fights with that.
- Network: VirtIO (paravirtualized), bridged to
vmbr0or whichever bridge has your LAN on it.
Finish the wizard but don't start the VM yet.
Step 3: Attach your real disks
This is the step that actually matters. You have two reasonable options.
Option A — Pass through individual disks by ID. SSH into the Proxmox host and list your disks:
ls -la /dev/disk/by-id/Find the disks you want to hand to TrueNAS (not your Proxmox boot disk) and note their by-id paths — something like ata-WDC_WD40EFRX-68N32N0_WD-XXXXXXXX. Then, with the VM stopped, attach each one:
qm set 100 -scsi1 /dev/disk/by-id/ata-WDC_WD40EFRX-68N32N0_WD-XXXXXXXX
qm set 100 -scsi2 /dev/disk/by-id/ata-WDC_WD40EFRX-68N32N0_WD-YYYYYYYYReplace 100 with your VM's actual ID, shown in the Proxmox UI. Always use the by-id path here, never /dev/sdb or similar — drive letters can shuffle around on reboot, and you really don't want TrueNAS building a pool on the wrong disk because of that.
Option B — Pass through the whole HBA controller. If your disks sit behind a dedicated controller card, you can hand the entire card to the VM, which is what most people with server-grade hardware actually do. Enable IOMMU first by adding intel_iommu=on (Intel) to your kernel command line — on Proxmox 8/9 that's usually /etc/kernel/cmdline if you're using systemd-boot, or your GRUB config otherwise — then run update-initramfs -u -k all and reboot. Find your controller with lspci -nn, then attach it:
qm set 100 -hostpci0 03:00.0Swap 03:00.0 for whatever PCI address lspci showed for your card. This method is a bit more setup up front, but TrueNAS then sees the disks exactly as if it were running on bare metal, SMART data and all.
Whichever option you pick, don't attach the disks as regular Proxmox virtual disks. A virtual disk sits behind Proxmox's own storage layer, which hides SMART attributes and adds a layer TrueNAS's health monitoring can't see through. It'll work, technically, right up until a drive is dying and TrueNAS has no idea.
Step 4: Install TrueNAS
Start the VM and open its console from the Proxmox UI. The TrueNAS installer boots from the ISO and asks which disk to install onto — pick the small 32 GB boot disk you created in Step 2, not any of the disks you passed through. Those are for your data pool later, and the installer will happily let you pick the wrong one if you're not paying attention.
Set a root password when asked, let it finish, then shut down, remove the ISO from the VM's CD-ROM drive (Hardware tab → CD/DVD Drive → Do not use any media), and boot again. Forgetting to eject the ISO is the single most common reason people end up stuck back at the installer on the next boot.
Step 5: First-boot setup
Once it's booted, the console shows the IP address TrueNAS picked up via DHCP. Open that IP in a browser (it'll be plain HTTP or self-signed HTTPS depending on version — your browser will warn you, that's expected) and you'll land in the setup wizard, where you create an admin account and set a few basics.
Step 6: Create your first pool and share
In the TrueNAS UI, go to Storage and start the pool creation wizard. Your passed-through disks should show up here by their real model and serial number — a good sign that passthrough is working correctly. Pick a layout (mirror for two disks, RAIDZ1 for three or more if you want to survive one disk failure) and let it build the pool.
From there, create a dataset under Datasets, then head to Shares to add an SMB share (for Windows and Mac clients) or NFS (for Linux and other VMs). Both take a couple of minutes to set up and you'll be browsing the share from another machine right after.
Commands Explained
| Command | What it does |
|---|---|
ls -la /dev/disk/by-id/ | Lists disks by their stable hardware ID instead of the reboot-dependent /dev/sdX name. |
qm set VMID -scsi1 /dev/disk/by-id/... | Attaches a specific physical disk to a stopped VM as a raw passthrough disk, bypassing Proxmox's virtual disk layer. |
lspci -nn | Lists PCI devices on the host along with their vendor/device IDs, used to find your HBA's address. |
qm set VMID -hostpci0 03:00.0 | Passes an entire PCI device, like an HBA controller, directly through to a VM. |
update-initramfs -u -k all | Rebuilds the initramfs for all installed kernels so IOMMU-related module changes take effect on next boot. |
Common Errors
"No disks available" in the TrueNAS pool wizard. Almost always means the passthrough step didn't actually happen — you're looking at a VM with only its boot disk attached. Shut down, double check qm config VMID on the Proxmox host, and confirm the scsi1/hostpci0 lines are there.
Disk shows up, but SMART data is blank. This is the telltale sign the disk was attached as a regular virtual disk rather than raw passthrough. Undo it and reattach using the by-id method from Step 3.
VM boots straight back into the installer after setup. The ISO is still mounted as boot media. Detach it from the CD-ROM drive in the Hardware tab and reboot.
Black screen after selecting a boot option. Usually a display driver mismatch under OVMF. Switch the console viewer to SPICE instead of the default, or try the VM's serial console — both work fine for TrueNAS once you're past the installer.
Troubleshooting
If pool creation stalls or the UI feels sluggish, check that ballooning is actually off — it's easy to tick the box in the wizard and then find it re-enabled after an edit. Go to the VM's Hardware tab, edit Memory, and confirm minimum equals maximum.
If TrueNAS can't reach the network, or the web UI won't load from the IP shown on the console, check the bridge you picked during VM creation actually has an uplink — it's an easy thing to get wrong if your host has more than one NIC or bridge.
If a passed-through HBA doesn't show up inside the VM at all, IOMMU probably isn't actually enabled. Run dmesg | grep -e DMAR -e IOMMU on the Proxmox host after reboot — if you see nothing, double check the kernel command line edit actually took and that you rebuilt initramfs afterward.
Best Practices
Keep TrueNAS's own boot disk small and simple — a 32 GB virtual disk is fine, and there's no reason to make it bigger since your data lives on the passed-through pool, not here.
Never mix a disk that's part of your ZFS pool with anything Proxmox also touches. Give TrueNAS exclusive, dedicated disks.
It's fine to take an occasional Proxmox-level snapshot or backup of the small boot VM as a safety net for the OS install itself, but don't rely on that for your actual data — TrueNAS's own ZFS snapshots and, ideally, replication to a second pool are what protect the files that matter.
Give the VM a fixed, dedicated amount of RAM rather than the smallest number that boots. ZFS performance leans heavily on how much it can cache in the ARC, and starving it defeats a good chunk of the point of running ZFS at all.
Frequently Asked Questions
Can I just use a regular Proxmox virtual disk for my storage pool instead of passthrough?
You can, but you shouldn't. You'll lose SMART monitoring and add an unnecessary translation layer between TrueNAS and the physical disk. Passthrough is the whole reason people run TrueNAS instead of just using Proxmox's own ZFS storage.
How much RAM does TrueNAS Scale actually need?
8 GB is a reasonable floor for a small home NAS. More helps if you plan to run TrueNAS's built-in apps alongside file sharing, since those compete with ZFS for the same memory.
Do I need ECC RAM to run TrueNAS safely?
No. ECC reduces the (already small) risk of memory errors corrupting data before ZFS ever checksums it, but plenty of home setups run fine on non-ECC RAM. It's a nice-to-have, not a requirement.
Can I update TrueNAS with apt since it's Debian-based underneath?
Don't. TrueNAS explicitly warns that updating any way other than through its own web interface can leave the system inoperable. Stick to the built-in updater.
What if I don't have a spare HBA card — can I still pass through disks?
Yes, individual disk passthrough by by-id path works fine for onboard SATA disks too. It's a little more manual per-disk, but functionally equivalent for a handful of drives.
Conclusion
The whole process comes down to one decision that actually matters: get real disks in front of TrueNAS instead of virtual ones, and everything downstream — snapshots, SMART monitoring, pool health — works the way it's supposed to. The VM settings, the installer, the setup wizard are all pretty forgiving by comparison.
Once the pool's built and the first share is mounted somewhere, this stops feeling like "a VM running a NAS" and starts just being your NAS. That's really the point of doing it this way on Proxmox in the first place.