How to Create a New User in Proxmox VE (Step-by-Step for Beginners)

Introduction

If you've been running Proxmox VE for a while, there's a good chance you're logging in as root@pam every single time. It works, sure. But it's also the digital equivalent of handing out your house keys to anyone who needs to water your plants. One typo in a shell command as root and you're not watering plants anymore — you're explaining to your family why the NAS is gone.

Creating a separate user account is one of those five-minute jobs that people put off for months. Then they clone a VM at 1 a.m., fat-finger a qm destroy, and wish they'd set up a limited account weeks ago. This guide walks through creating a real user in Proxmox VE, giving them a password, and handing them just enough access to actually be useful — not full control of your cluster.

We'll use Proxmox VE 9.x for the screenshots and command examples below. The workflow is nearly identical on 8.x; a couple of menu labels have shifted slightly, but the underlying tools haven't changed.

What You Will Learn

• The difference between the two authentication realms Proxmox VE ships with by default
• How to create a user from the web GUI
• How to create the same user from the command line with pveum
• How to set a password and give the account something to actually do
• Why a brand-new user sees an empty screen after logging in (and how to fix that)
• Common mistakes and the errors they produce

What Is This Feature?

Proxmox VE has its own user database, completely separate from your operating system's user accounts. This is called user management, and it's built around two ideas: realms and roles.

A realm is where an account's identity actually lives. Proxmox VE ships with two realms out of the box:

• Linux PAM (pam) — authenticates against real Linux accounts on the host, the same ones you'd create with adduser. If you already have a Linux user, you can let them log into the Proxmox GUI with the same username and password.
• Proxmox VE authentication server (pve) — a self-contained user database, unrelated to the underlying OS. Passwords are stored (hashed) in /etc/pve/priv/shadow.cfg and managed entirely inside Proxmox.

You can also add LDAP, Active Directory, or OpenID Connect realms for larger setups, but for a homelab or a small business server, PVE-realm accounts are almost always the right call — no separate Linux account required, and the user can change their own password from the GUI.

A role, on the other hand, decides what a user is actually allowed to do once they're logged in. Creating the account and giving it permission to do something are two separate steps, and skipping the second one is the single most common source of confusion for anyone doing this for the first time.

Why Would You Use It?

The honest reason most people finally do this: someone other than them needs access, and handing over the root password felt wrong even as they were typing it into a chat window.

A few situations where a dedicated account earns its keep:

• A family member or roommate needs to start and stop a Plex VM without being able to touch anything else.
• A junior admin at a small business needs to manage a handful of VMs, but shouldn't be able to delete the whole cluster on a bad day.
• You want a backup-only account for a monitoring script, so a leaked credential doesn't hand over the keys to everything.
• You just want your own daily-driver login that isn't root, so a stray command doesn't have unlimited blast radius.

None of this requires deep RBAC planning. That's a separate, more advanced topic if you need fine-grained delegation across a whole team. For a single new user with a specific, limited job, the steps below are all you need.

Prerequisites

• A working Proxmox VE 8.x or 9.x installation with GUI access on port 8006
• Root access, either through the web interface or an SSH session to the host
• About five minutes

Nothing else. You don't need to touch the network, install anything, or reboot.

Step-by-Step Tutorial

Method 1: Creating a User from the Web GUI

Log into the Proxmox VE web interface as root. In the left-hand tree, click Datacenter, then open Permissions > Users in the sidebar.

1. Click Add at the top of the Users table.
2. In the User name field, enter a short username — no spaces, no @ symbol. Something like jsmith or backupbot.
3. Leave Realm set to Proxmox VE authentication server unless this person already has a Linux login on the host.
4. Type a password in the Password field. Proxmox VE enforces a minimum length, so keep it above 8 characters or the form will bounce back at you.
5. Optionally fill in first name, last name, and email — useful once you have more than two or three accounts and need to tell them apart at a glance.
6. Leave Enabled checked and Expire blank unless you want the account to stop working on a specific date.
7. Click Add.

At this point the user exists, but they can't do anything yet. If they try to log in right now, they'll land on a completely empty dashboard — no VMs, no storage, nothing. That's expected, and we'll fix it in the next step.

Giving the User Something to Do

Still under Datacenter, click Permissions (not Users — the top-level Permissions view this time).

1. Click Add > User Permission.
2. Path — this is the scope of access. For a single VM, browse to something like /vms/100. For everything, use /.
3. User — select the account you just created (it'll show as jsmith@pve).
4. Role — pick a built-in role. PVEVMUser is a good starting point: it lets someone start, stop, and use the console of VMs in the given path, without letting them create, delete, or reconfigure anything.
5. Leave Propagate checked if the path is a folder-like scope (for example a whole pool) and you want the permission to apply to everything inside it.
6. Click Add.

Log out and log back in as the new user to confirm they see exactly what you expect — no more, no less.

Method 2: Creating a User from the Command Line

SSH into the Proxmox host and run:

pveum user add jsmith@pve --password "ChangeThisPassword123" --firstname John --lastname Smith --comment "Homelab operator account"

That single command does what the GUI form did across several fields. Next, assign a role the same way you would in the GUI, but with pveum acl modify:

pveum acl modify /vms/100 --users jsmith@pve --roles PVEVMUser

If you'd rather use an existing Linux account instead of a PVE-realm one:

useradd -m sarah
pveum user add sarah@pam --comment "Backup operator, existing Linux account"

Note there's no --password flag for the PAM example — the password already lives on the Linux system, managed with passwd sarah, not through Proxmox.

Commands Explained

Command	What It Does
pveum user add <user>@<realm>	Creates a new user in the specified realm. This is the CLI equivalent of the Datacenter > Permissions > Users > Add button.
--password "..."	Sets an initial password. Only meaningful for the pve realm — PAM accounts use the Linux password instead.
pveum passwd <user>@pve	Changes the password for an existing PVE-realm user. Prompts you interactively rather than taking the password as an argument, which avoids it sitting in your shell history.
pveum acl modify <path> --users <user> --roles <role>	Grants a role to a user at a given path in the resource tree — a VM, a storage, a pool, or the whole datacenter with /.
pveum user list	Prints every user currently defined, across every realm. Handy for spotting stale accounts.
pveum user delete <user>@<realm>	Removes a user entirely. Doesn't touch any permissions granted separately — those get cleaned up automatically once the user is gone.

Common Errors

A handful of mistakes show up over and over with new accounts. Here's what they look like and what's actually going on.

Symptom	Cause
User logs in and sees a completely blank GUI, no VMs listed	The account exists but has no permissions assigned yet. Go back to Datacenter > Permissions and add one.
user 'name@pam' does not exist when adding via GUI	You picked the PAM realm for a user who doesn't have a matching Linux account on the host. Either create the Linux user first with adduser, or switch the realm to pve.
Password field rejected in the GUI	Proxmox enforces a minimum password length (8 characters). Short or blank passwords get bounced silently back to the form.
PAM user can log into Proxmox but their password doesn't match what you expect	PAM authentication checks the actual Linux password. If it was changed with passwd on the host after the Proxmox account was created, use the new one — Proxmox never stores it separately.
New user can see a VM in the tree but the console button is greyed out	The assigned role doesn't include console access. PVEVMUser covers this; a narrower custom role might not.

Troubleshooting

If a user reports they can log in but can't do the one thing you set them up for, check the permission path first. It's the single most common gap. Go to Datacenter > Permissions and filter by user — if nothing shows up, that's your answer.

If you locked yourself out of testing because you're logged in as the new user in a different browser tab and can't get back to root, that's not actually a lockout — just open a private/incognito window and log in as root there. Proxmox VE sessions are tied to the browser, not the server.

Forgot a PVE-realm user's password? You don't need to delete and recreate the account. As root, run:

pveum passwd jsmith@pve

It'll prompt for a new password twice and update it immediately — the user doesn't need to be logged out first.

If a PAM-realm account refuses to log in at all, confirm the Linux user actually exists with id sarah on the host. It's easy to create the Proxmox side of a PAM account and forget the matching useradd step, or do them in the wrong order.

Best Practices

Stop logging in as root for day-to-day work. Create yourself a PVE-realm account with the access you actually need, and save root for the rare occasions you genuinely need it — a package upgrade, a cluster join, that kind of thing.

Give each account only the access it needs, scoped to the narrowest path that makes sense. A monitoring script that only reads VM status doesn't need write access to storage. A family member who watches Plex doesn't need access to your pfSense VM.

Use PVE realm for anyone who doesn't already have a reason to log into the Linux host directly. It keeps Proxmox accounts and system accounts cleanly separated, and it means deleting a Proxmox user never accidentally leaves a stray Linux login behind.

Name accounts by purpose, not just by person, when it makes sense — backupbot@pve tells you what it's for at a glance six months from now, in a way svc1@pve never will.

Review pveum user list every so often. Test accounts and one-off contractor logins have a way of sticking around long after they're needed.

Frequently Asked Questions

Do I need to create a matching Linux user for a PVE-realm account?

No. PVE-realm accounts are entirely self-contained inside Proxmox and have nothing to do with the underlying Linux system.

Can a new user log in over SSH?

Not with a PVE-realm account — those only work for the web GUI and API. SSH access requires an actual Linux account on the host, which is a separate and much more sensitive thing to hand out.

What's the difference between a user account and an API token?

A user account is for a person logging into the GUI. An API token is tied to a user but used for scripts and automation, and it can be revoked independently without touching the user's password.

Can I use an email address as the username?

The username itself has to be a plain string without an @ — that character is reserved for separating the name from the realm. You can still store an email address in the optional Email field for reference.

How do I remove a user later?

Datacenter > Permissions > Users, select the account, and click Remove — or run pveum user delete jsmith@pve from the shell. Their assigned permissions disappear along with them.

What happens if I forget to assign a role?

The account works fine for logging in, but the user sees an empty interface. It's not broken — it just has nothing to show yet.

Conclusion

Setting up a proper user account takes about as long as reading this guide did. What you get in return is a Proxmox host where root stays reserved for the things that actually need it, and everyone else — family, coworkers, scripts — gets exactly the access they need and nothing more. It's a small habit, but it's the kind that saves you from a genuinely bad afternoon down the line.