If you've been running Proxmox VE for a while, you've probably built up a pile of VMs and containers that all belong to the same project. Maybe you've got three guests running your home Plex stack, four more for a Kubernetes test cluster, and a couple of Windows VMs you spun up just to test something for work. Right now, managing permissions or storage access for each of those groups probably means clicking into every single VM one at a time.

There's a Proxmox VE feature built specifically to fix that, and almost nobody outside of larger deployments seems to know it exists: resource pools. They've been in Proxmox VE since well before version 5, and they still work the same way in current 8.x and 9.x releases, but the GUI tab is easy to miss if you've never gone looking for it.

This tutorial walks through what pools actually do, how they're different from tags and from Proxmox's user permission system, and how to set one up from scratch using both the web interface and the pveum command line tool.

What You Will Learn

By the end of this guide you'll be able to:

  • Explain what a resource pool is and how it differs from tags and from regular ACLs
  • Create a pool and add VMs, containers, and storage to it through the GUI
  • Do the same thing from the shell using pveum pool commands
  • Assign a permission to an entire pool at once, instead of one resource at a time
  • Recognize the most common mistakes people make with pools, and how to fix them

What Is This Feature?

A resource pool in Proxmox VE is a named container that groups together VMs, LXC containers, and storage IDs. It doesn't change how those resources behave. A VM in a pool still runs exactly the same as a VM outside one. What a pool changes is how you manage access and organization for that group as a single unit.

Think of it less like a folder and more like a tag that you can attach permissions to. In fact, pools and tags get confused a lot, so it's worth being precise about the difference.

Tags (the colored labels you can stick on a VM from the summary panel) are purely cosmetic and searchable. They help you find things in the resource tree, and that's it. You can't assign a permission to a tag.

Pools, on the other hand, are a real permission path. Proxmox's access control system lets you grant a role to a user or group at the path /pool/<poolid>, and that permission applies to every VM, container, and storage entry that's a member of the pool, automatically. Add a new VM to the pool later, and it inherits the same access rules without you touching the permissions screen again.

If you've read about Proxmox's role-based access control (RBAC) system before, pools slot in as one of several permission paths, alongside things like /vms/100 or /storage/local. The difference is that a pool path represents a group of resources rather than one resource, which is the whole point.

Why Would You Use It?

The honest answer: most single-user homelabs don't need pools at all. If you're the only person logging into your Proxmox box, there's no one to delegate access to, and a pool won't do much for you beyond light organization.

Pools start to matter the moment more than one person, or more than one automation account, touches your cluster. A few real situations where they earn their keep:

  • You've got a developer who needs to start, stop, and console into five specific test VMs, but shouldn't be able to touch anything else on the host, including your storage configuration or other people's VMs.
  • You're running a small MSP or homelab-turned-side-business setup, and each client's VMs need to be walled off so one client's user account can never see another client's guests.
  • You want a backup automation account (maybe an API token) that's scoped to only back up a specific group of VMs, rather than having blanket access to everything on the node.
  • You just want a cleaner way to see "everything related to Project X" in one place, even if you don't need the permission side of it yet.

I'd skip pools if you're the sole admin and don't plan on adding other users any time soon. But if you're about to hand a login to a coworker, a client, or even a slightly-too-curious family member, pools are the cleanest way to box them in without babysitting individual VM permissions.

Prerequisites

Before you start, make sure you've got:

  • A working Proxmox VE installation (this guide was tested on 8.3 and 9.0; the pool feature hasn't changed meaningfully across recent versions).
  • Root or PVEAdmin-level access to the web GUI, since creating pools and assigning permissions requires elevated rights.
  • At least one existing VM or LXC container, and ideally one storage entry, so you have something to add to a pool. It's fine to follow along with just a single test VM.
  • Shell access to the node (via the built-in noVNC console, or SSH) if you want to try the pveum command line examples. This is optional; everything here can be done from the GUI alone.

You don't need a subscription or the enterprise repository for any of this. Pools and RBAC are fully available on the free, no-subscription version of Proxmox VE.

Step-by-Step Tutorial

Step 1: Create the pool

Log into the Proxmox VE web interface and click Datacenter in the left-hand tree. Then open Permissions and click the Pools sub-tab. This is the part people miss, since "Pools" isn't its own top-level item; it lives tucked under Permissions.

Click Create. You'll get a small dialog asking for:

  • Pool - a short identifier, letters, numbers, hyphens and underscores. Something like project-x or client-acme works well. Spaces aren't allowed.
  • Comment - optional, but useful once you have five or six pools and can't remember what each one is for.

Click Create again and the pool shows up in the list immediately. Right now it's empty. That's expected.

Step 2: Add VMs, containers, and storage to the pool

Click on the pool you just created, then open its Members tab. Click Add, and you'll get two choices: adding VMs/containers, or adding storage.

Pick the guests you want in the pool and confirm. You can add and remove members at any time later, and a VM can only belong to one pool at a time (Proxmox will block you from adding a guest that's already in a different pool unless you explicitly move it).

Repeat for storage if you want backup targets or disk storage scoped to this pool as well. This part is optional. A lot of people only pool VMs and containers and leave storage permissions handled separately.

Step 3: Create the user or group you're delegating to

If you haven't already, go to Datacenter > Permissions > Users and create a new user, or use Groups if you're managing more than one person the same way. Give the account a username in the pve realm (or your LDAP/AD realm if you've set one up) and a password.

You don't need to touch any permission settings on this screen. That happens in the next step.

Step 4: Assign a role to the pool

Go to Datacenter > Permissions and click Add > Pool Permission. You'll be asked for:

  • Pool - select the pool from Step 1.
  • User (or Group) - the account from Step 3.
  • Role - the level of access you want to grant.

For a developer who should manage VMs but not the underlying host, PVEVMUser is usually the right call. It lets someone start, stop, and open the console of guests in the pool, without giving them access to storage configuration, backups, or other pools. If you want someone to only look and never touch anything, use PVEAuditor instead.

Click Add, and the permission takes effect right away. Log in as that user (or ask them to) and confirm they only see the VMs and containers that belong to the pool.

Step 5: Test it properly

This step gets skipped constantly, and it's the one that actually catches mistakes. Open a private browser window, log in as the test account, and check three things: can they see the resources they should, can they NOT see resources outside the pool, and can they actually perform the action you expected (start a VM, open a console, whatever the role is supposed to allow). It takes two minutes and saves you from finding out the hard way that someone had more access than intended.

Commands Explained

Everything above can be done from the shell using pveum, Proxmox's user and permission management CLI tool. This is handy if you're scripting the creation of pools as part of a larger setup process.

pveum pool add project-x --comment "Project X test environment"

Creates a new pool with the ID project-x. The --comment flag is optional but worth using; six months from now you won't remember why pool-7 exists otherwise.

pveum pool modify project-x --vms 100,101,102

Adds VMIDs 100, 101, and 102 to the pool. You can pass a comma-separated list to add several guests in one command. Run the same command again later with different VMIDs to add more.

pveum pool modify project-x --vms 100 --delete 1

Removes VMID 100 from the pool. The --delete flag flips the command from "add these" to "remove these," which trips people up the first time since it's not obvious from the syntax alone.

pveum pool modify project-x --storage local,local-zfs

Adds the storage IDs local and local-zfs to the pool, the same way --vms adds guests.

pveum acl modify /pool/project-x --users devuser@pve --roles PVEVMUser

Grants the PVEVMUser role to devuser@pve on the pool path. This is the CLI equivalent of the "Pool Permission" dialog from Step 4. You can pass --groups instead of --users if you're assigning to a group, and you can list multiple roles or users separated by commas.

pveum pool delete project-x

Deletes the pool entirely. This does not delete the VMs, containers, or storage that were members. It only removes the grouping and any permissions tied to the pool path.

Common Errors

A few things people run into the first time they touch pools:

"Permission check failed" for a user who's clearly supposed to have access. Nine times out of ten this is because the permission was added to the pool, but the user's role doesn't actually cover the action they're trying to take. PVEAuditor, for example, can view everything in the pool but can't start or stop a single VM. Check the exact role, not just whether a permission exists.

A VM won't add to a pool because it's "already a member of another pool." Proxmox only allows a guest to belong to one pool at a time by default. Either remove it from the old pool first, or use --allow-move with pveum pool modify if you want to move it directly.

The user can see the VM in the resource tree but the console button is greyed out. This usually means the role grants viewing (like PVEAuditor or PVEPoolUser) but not console access. PVEVMUser includes console rights; the read-only roles don't.

Deleting a pool doesn't remove the VMs. This isn't actually an error, just a common assumption. Pools are purely an organizational and permission layer. Deleting one is safe and never touches the guests or storage that were in it.

Troubleshooting

If permissions don't seem to be working the way you expect, work through this order:

  1. Confirm the pool actually has the members you think it does. Open the pool's Members tab and check the list directly rather than trusting memory.
  2. Confirm the permission is attached to the pool path (/pool/<poolid>) and not accidentally added to an individual VM path that looks similar in the list.
  3. Check for a conflicting permission somewhere else. If the same user has a permission set directly on one of the VMs inside the pool, that more specific path can override what the pool grants.
  4. Log out and back in as the affected user (or have them do it). Proxmox does cache some permission state per session, and a stale login occasionally shows outdated access.
  5. Use Datacenter > Permissions and filter by user to get a full list of every permission that account has, from every path. It's the fastest way to spot something that shouldn't be there.

Best Practices

A handful of habits that make pools less painful down the road:

Name pools after the project or client, not the person. client-acme ages a lot better than johns-vms, especially once John leaves and someone else takes over the account.

Use groups instead of individual user permissions wherever more than one person needs the same access. Assign the role to the group, then add and remove users from the group as people join or leave. It's far less error-prone than tracking down every individual permission when someone's role changes.

Don't put your entire infrastructure in a single pool "just in case." Pools are cheap to create. A pool per project or per client keeps the blast radius small if a permission ever gets misconfigured.

Combine pools with tags rather than picking one or the other. Tags help you find things visually; pools handle the actual access control. They solve different problems and work fine side by side.

Re-check pool membership after big changes, like migrating a VM to a new node or restoring it from backup with a new VMID. Restored VMs in particular sometimes come back with a different ID and won't automatically rejoin their old pool.

Frequently Asked Questions

Do pools work with LXC containers, or just VMs?

Both. A pool can contain any mix of QEMU VMs and LXC containers, plus storage entries, all in the same group.

Can a VM belong to more than one pool at once?

No, not by default. Proxmox treats pool membership as exclusive per guest unless you explicitly move a VM using the --allow-move option.

Do I need a paid subscription to use pools?

No. Pools, users, groups, and RBAC are all part of the free Proxmox VE platform, with or without the enterprise repository enabled.

What's the difference between PVEPoolUser and PVEPoolAdmin?

PVEPoolUser can view a pool and its members. PVEPoolAdmin can additionally create, modify, and delete pools. Neither role by itself grants control over the VMs inside the pool; you still need a role like PVEVMUser for that.

If I delete a pool, does anything happen to the VMs inside it?

Nothing at all. The VMs, containers, and storage keep running exactly as before. Only the grouping and any permissions tied to that pool path disappear.

Can I nest pools inside other pools?

No. Pools in Proxmox VE are a flat structure. If you need finer-grained grouping, you'll need to use naming conventions or tags alongside your pools rather than nesting.

Conclusion

Pools solve a narrow but real problem: giving someone access to a specific group of VMs and containers without either sharing your root login or clicking through permission dialogs one resource at a time. If you're running Proxmox solo, you can safely ignore all of this. The moment a second person, a client, or an automation account needs scoped access, though, setting up a pool takes about five minutes and saves you from a much messier permissions cleanup later.

Start small: pick one project you already have running, group its VMs into a pool, and assign a role to a test account before you roll it out to anyone real. Once you've seen it work end to end, adding the next pool is just repeating the same five steps.