Introduction
Fire up a Proxmox VE host that's been running for a year or two and you'll usually see the same thing: a resource tree full of VMs and containers named vm1, vm2, test, and test2, with nothing to tell you which one runs your DNS server and which one you spun up to test a kernel patch in 2024. Renaming everything after the fact is a pain, and half the time you can't remember what's safe to delete.
Proxmox actually has a built-in answer to this, and it's one of the more underused features in the whole platform: tags. They've been part of Proxmox VE since version 7, they take about thirty seconds to add, and almost nobody talks about them. This guide walks through what they are, how to add them from both the GUI and the command line, and how to actually use them to find things again once your homelab has grown past a dozen guests.
What You Will Learn
By the end of this article you'll know how to add and remove tags on VMs and containers using both the web interface and the qm and pct commands, how to color-code tags so they're easy to scan at a glance, and how to use the search bar in the resource tree to filter your inventory down to exactly what you're looking for. We'll also cover the naming conventions that actually hold up once you've got fifty guests instead of five.
What Is This Feature?
A tag in Proxmox VE is a short piece of text metadata attached to a VM or LXC container. Think of it as a label you stick on a guest — it doesn't change how the VM boots, how much RAM it uses, or anything about its actual configuration. It's purely for your own organization.
Tags show up as small colored pills next to the guest's name in the resource tree on the left side of the Proxmox web interface, and again on the guest's Summary tab. A single VM or container can carry multiple tags at once, so you might tag a web server with both prod and web, or a test VM with test and ubuntu.
This is different from the Notes field you'll also find on the Summary tab. Notes are free-form text meant for longer descriptions — think "migrated from bare metal in March, needs 4 vCPUs minimum." Tags are short, structured, and built for filtering. Use notes for context a human needs to read; use tags for anything you'd want to search or group by.
Why Would You Use It?
If you're running three or four VMs, you honestly don't need this. You'll remember what everything is. The value shows up once your Proxmox host — or worse, your cluster — starts accumulating guests faster than your memory can keep up.
A few situations where tags earn their keep:
- You run a mix of production and test VMs on the same node and want to see at a glance which ones you can safely reboot without waking anyone up.
- You manage guests for more than one client or project and need to tell them apart without renaming every VM to include a client prefix.
- You're testing different operating systems or software versions and want to filter the resource tree down to "just the Rocky Linux VMs" or "just the ones running PostgreSQL."
- You're part of a small team sharing one Proxmox cluster and want a lightweight way to signal ownership —
owner:sarah,owner:devteam— without setting up full role-based permissions for every guest.
None of this is mandatory. Plenty of homelab users never touch tags and get along fine. But if you've ever stared at a list of twenty VMs trying to remember which one was the Pi-hole test box, this is the feature that fixes it.
Prerequisites
You don't need much to follow along:
- A working Proxmox VE installation — this works the same on Proxmox VE 7.x, 8.x, and 9.x, since tags haven't changed much since they were introduced.
- At least one existing VM or LXC container to practice on. It doesn't need to be running; tags work on stopped guests too.
- Access to the Proxmox web interface, and optionally SSH or console access if you want to try the command-line method.
- A user account with permission to modify the guest — if you're logged in as root@pam or an administrator, you're covered.
Step-by-Step Tutorial
Step 1: Add a tag from the web interface
Log in to the Proxmox VE web interface and click on any VM or container in the left-hand resource tree. On the Summary tab, look just below the guest's name — you'll see a small area labeled Tags with a pencil or plus icon next to it.
Click that icon, type a tag name, and press Enter. You can add several tags in the same box — just keep typing and hitting Enter for each one. Click the checkmark (or click away from the box) to save. The tag appears immediately as a small colored pill next to the VM's name, both here and in the resource tree.
To remove a tag, click the same edit icon and click the small "x" on the tag you want to delete.
Step 2: Add a tag from the command line
If you'd rather script this — or you're tagging a dozen guests at once and clicking through the GUI sounds miserable — SSH into your Proxmox host and use qm for virtual machines or pct for containers.
For a VM:
qm set 101 --tags prod;webFor a container:
pct set 201 --tags test;ubuntuNotice the tags are separated by semicolons, not commas. This trips people up the first time — a comma will just get treated as part of a single (broken) tag name instead of a separator.
One catch: qm set --tags replaces the entire tag list, it doesn't add to it. If VM 101 already has the tag prod and you run qm set 101 --tags web, you'll end up with only web — prod is gone. Always include every tag you want the guest to have, not just the new one.
Step 3: Check what tags a guest currently has
Before you overwrite anything, it's worth checking the current tag list:
qm config 101 | grep tagsOr for a container:
pct config 201 | grep tagsThis prints the raw tags: line from the guest's configuration file, which is exactly what you're about to overwrite. Copy it, add your new tag, and pass the full list back to --tags.
Step 4: Color-code your tags
By default, Proxmox assigns tag colors automatically based on a hash of the tag name — functional, but not something you control. If you want specific colors (red for anything production, for example), go to Datacenter in the resource tree, then Options, and find Tag Style Override. Click Edit.
Here you can set a manual color map. The format is tagname:hexcolor, with an optional second hex code for the text color, and multiple mappings separated by semicolons — something like prod:CC0000:FFFFFF;test:2E8B57. You can also change the Shape of tags (full pill, circle only, or a dense compact style for smaller screens) and whether tags sort alphabetically or in the order you defined them.
If you prefer the command line, the same setting can be pushed through pvesh:
pvesh set /cluster/options --tag-style color-map=prod:CC0000:FFFFFFStep 5: Search and filter by tag
This is where tags actually pay off. At the top of the resource tree there's a search box (the magnifying glass icon, or just Ctrl+Shift+Space in newer versions). Start typing a tag name and the tree filters down to only the guests carrying that tag — right alongside matches on VM name, VMID, and node name, since the search box checks all of them at once.
This one habit is honestly the whole reason to bother tagging in the first place. Tag everything consistently for a week and searching your Proxmox host stops being "scroll and squint" and starts being "type three letters."
Commands Explained
| Command | What it does |
|---|---|
qm set <vmid> --tags tag1;tag2 | Sets the complete tag list for a virtual machine, replacing whatever was there before. |
pct set <ctid> --tags tag1;tag2 | Same behavior as above, but for LXC containers. |
qm config <vmid> | Prints the full configuration of a VM, including its current tags: line — use this before overwriting tags so you don't lose any. |
pct config <ctid> | Same as above, for containers. |
pvesh set /cluster/options --tag-style ... | Updates datacenter-wide tag display settings — colors, shape, and sort order — from the command line instead of the GUI. |
Common Errors
Most tag-related problems aren't errors in the strict sense — Proxmox rarely throws a hard failure over a tag. What you'll actually run into is quieter than that:
- Tags silently disappearing. This is almost always the "set instead of add" behavior from Step 2. You ran
qm setwith a partial tag list and it replaced everything instead of appending. - A tag with a comma in it looks broken. Proxmox uses semicolons as the separator. A tag typed as
prod,webgets stored as one literal tag called "prod,web" instead of two tags. - Uppercase letters get lowercased automatically. If you type
PRODand it saves asprod, that's expected — Proxmox normalizes tag case by default. It's not a bug, and it's why consistent lowercase naming matters more than it seems like it should.
Troubleshooting
If a tag you added through the GUI doesn't show up in the resource tree, try refreshing the page first — the web interface caches guest metadata and occasionally needs a manual reload to pick up a change made moments earlier.
If tags set through qm or pct aren't appearing in the GUI at all, double check you're editing the right guest ID. It's an easy mistake on a host with VMs in the 100s and containers in the 200s — running qm set 201 --tags test against what's actually a container ID will fail with a "VM 201 does not exist" style error, since qm only looks at virtual machines.
If your color map isn't applying, check the syntax in Datacenter > Options > Tag Style Override carefully. A missing semicolon between two tag-color pairs will usually cause the whole color map to be ignored rather than partially applied, which makes the mistake easy to miss at a glance.
Best Practices
A few habits make tags genuinely useful instead of just decorative:
- Pick a small, consistent vocabulary before you start tagging everything. Something like an environment tag (
prod,test,dev), a purpose tag (web,db,dns), and an OS tag (ubuntu,debian,windows) covers most homelabs without turning into a mess. - Stick to lowercase letters, numbers, and simple separators like hyphens or colons. Proxmox will lowercase things for you anyway, so fighting it just leads to confusion later.
- Tag as you create, not after. It takes five seconds during VM creation and saves you from a tedious cleanup pass six months later.
- Don't over-tag. A VM with twelve tags is no easier to find than one with none — three or four meaningful tags beats a pile of noise.
Honestly, the color-coding step is the one most people skip, and it's the one that makes the biggest visual difference once you've got more than ten guests on screen at once. A quick glance at red versus green pills tells you more than reading twenty VM names ever will.
Frequently Asked Questions
Do tags affect VM performance or backups?
No. Tags are pure metadata stored in the guest's configuration file. They have no effect on CPU, memory, disk performance, or how vzdump backs up the guest.
Can I use tags to filter backup jobs?
Yes — when creating or editing a backup job in Datacenter > Backup, you can select guests by VMID, by pool, or by tag, so a job can target "everything tagged prod" instead of listing IDs manually.
Are tags shared across a cluster?
Yes. Tags are stored in the guest's configuration in /etc/pve, which is replicated across every node in a cluster, so a tag you add on one node is visible from any other node immediately.
Is there a limit to how many tags a VM can have?
There's no hard-documented limit, but practically speaking more than four or five tags per guest stops being useful. If you need that many, you're probably better off using the Notes field for detail and keeping tags to the essentials.
Can regular (non-admin) users add tags?
It depends on their permissions. A user needs the VM.Config.Options privilege on that specific guest to modify its tags, same as any other configuration change.
Conclusion
Tags aren't going to show up on anyone's "top ten Proxmox features" list, and that's exactly why most people never bother with them. But they cost almost nothing to use and solve a real problem the moment your homelab or small production cluster grows past the point where you can remember what everything is by name. Spend the next ten minutes tagging your existing VMs and containers, set up a color map you'll actually recognize at a glance, and the next time you're hunting for "that one test VM" you'll type a tag into the search box instead of scrolling through forty rows guessing.