Introduction

You've just spun up a fresh Proxmox VE install, you click "Create CT" to spin up your first container, and the template dropdown is empty. Or maybe you picked a template once, months ago, and now half the list is missing distros you know exist. Either way, you've run into pveam, the piece of Proxmox that almost nobody reads about until it stops working.

Container templates are the base images LXC containers get built from — think of them as the container equivalent of a VM's install ISO, except pre-built and ready to boot in seconds. Proxmox doesn't ship these templates with the installer. You have to go get them, and that's a manual step a lot of guides skip past with a single throwaway line.

This one doesn't skip past it. We're going to slow down on template management specifically: how the template list actually works, where the files end up on disk, why storage selection matters more than people expect, and what to do when downloads fail or the list won't populate.

What You Will Learn

  • What container templates are and how they're different from a VM's ISO or a Docker image
  • How to enable a storage location to actually hold templates
  • How to update, browse, download, and remove templates using both the GUI and the pveam command
  • What each pveam subcommand actually does under the hood
  • The errors that show up most often, and the boring reasons behind them
  • A few habits that keep your template storage from turning into dead weight

What Is This Feature?

pveam stands for Proxmox VE Appliance Manager. It's a command-line tool — and the engine behind the "CT Templates" button in the GUI — that manages the catalog of pre-built container images Proxmox can pull down and use to create LXC containers.

A quick refresher on LXC, since it matters here: LXC (Linux Container) is Proxmox's container technology, and it's a lighter-weight alternative to a full virtual machine. Instead of emulating hardware and booting a whole separate kernel, an LXC container shares the host's kernel and just gets its own isolated filesystem, processes, and network stack. That's why containers start almost instantly and use a fraction of the RAM a VM would for the same workload.

A template is a compressed archive (usually a .tar.zst or .tar.xz file) containing a minimal, pre-configured root filesystem for a given distribution — Debian, Ubuntu, AlmaLinux, and so on. When you create a container, Proxmox unpacks that archive into the container's storage and boots from it. No template, no container. That's the whole relationship in one sentence.

It's worth being clear about what a template is not. It's not a VM template (that's a different feature entirely, built around cloning an existing virtual machine). And it's not a Docker image — LXC templates boot a full init system and behave like a small, normal Linux install, not a single-process container.

Why Would You Use It?

You don't really choose to use pveam — you end up needing it the moment you want your first LXC container, and again every time you want a distro you haven't downloaded before. But understanding it directly, rather than through the "Create CT" wizard, pays off in a few specific situations.

You'll want it when the template dropdown in the GUI is empty on a brand new install — that's expected, not broken, and the fix is a single command. You'll want it when a storage location isn't showing up as an option for templates at all, because that's a storage configuration issue, not a download issue, and the two look identical from the wizard. And you'll want it when your local storage starts filling up with template archives you downloaded once, tested, and never touched again.

Homelab users run into this constantly because they experiment — a Debian 12 container, then a Debian 13 one, then three different Ubuntu LTS versions to compare. Each one leaves a file behind. None of that gets cleaned up automatically.

Prerequisites

  • A working Proxmox VE install (this guide applies to 8.x and 9.x — the pveam commands haven't changed between them)
  • Root access to the Proxmox host, either through the web-based Shell (Datacenter → your node → Shell) or SSH
  • Outbound internet access from the Proxmox host itself — templates download from Proxmox's own servers, so if the host is behind a restrictive firewall, this is where it'll show
  • At least one storage location with the Container Template content type enabled (we'll set this up below if you haven't already)

You don't need a container created yet. This is entirely about the template catalog, not any specific container.

Step-by-Step Tutorial

1. Confirm a storage location accepts templates

Not every storage type in Proxmox can hold container templates. Templates need a storage backend that supports the vztmpl content type, which in practice means directory-based storage — your default local storage, an NFS share, or a CIFS/SMB mount. Block-based storage like LVM-thin, ZFS-on-block, or Ceph RBD can't store templates directly, because those are built for raw disk images, not loose files.

Go to Datacenter → Storage, click your storage entry (usually local), and check the Content field. If Container Template isn't listed, click Edit and tick that box. This is the single most common reason people can't find their storage in the template download dialog — it's not a bug, the box just isn't checked.

2. Update the template database

Open a shell on your Proxmox host and run:

pveam update

This refreshes the local list of what's available from Proxmox's template repository. It doesn't download anything itself — it just syncs the catalog, the same way apt update refreshes package lists without installing packages. Proxmox also runs this automatically once a day through a system timer, but if your list looks stale or empty, running it manually is the first thing to try.

3. Browse what's available

pveam available

This dumps a long list — often 80+ entries — covering multiple versions of Debian, Ubuntu, AlmaLinux, Rocky Linux, Fedora, Alpine, and a set of pre-configured "turnkey" appliances (things like turnkey-wordpress or turnkey-nextcloud, which are full ready-to-run apps, not just base OS images).

To narrow it down, use the --section option:

pveam available --section system

That filters out the turnkey appliances and mail-related templates, leaving just the base distro images — the ones you'll use 95% of the time.

4. Download a template

Pick an exact template name from the output above (they're versioned and specific, like debian-13-standard_13.1-1_amd64.tar.zst) and download it to a storage location:

pveam download local debian-13-standard_13.1-1_amd64.tar.zst

The first argument is the storage ID, the second is the exact template filename. Copy-paste it rather than typing it from memory — a single wrong character in the version string and you'll get a "not found" error instead of a typo warning.

Prefer clicking instead of typing? In the GUI, go to your node, click the storage (e.g. local) in the left tree, open CT Templates, and hit the Templates button. That opens the exact same catalog pveam available shows, with a search box and a Download button — genuinely easier once you know the CLI names look intimidating for no real reason.

5. Verify it landed

pveam list local

This shows every template currently sitting on that storage, along with its size. A fresh Debian or Ubuntu template usually lands somewhere between 100 MB and 250 MB, so don't be surprised if it's bigger than you expected — these aren't the stripped-down 20 MB rootfs images some Docker base images use.

6. Remove templates you don't need anymore

pveam remove local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst

Note the format here — it's storage:vztmpl/filename, not just the filename. This is the one command in this whole workflow that trips people up, because every other pveam command just wants a plain filename.

Commands Explained

CommandWhat it does
pveam updateRefreshes the local catalog of available templates from Proxmox's servers. Run this first if your list looks empty or out of date.
pveam availableLists every template currently in the catalog, optionally filtered with --section system, mail, or turnkeylinux.
pveam download <storage> <template>Downloads a specific template into the named storage. Requires that storage to have the Container Template content type enabled.
pveam list <storage>Shows templates already downloaded onto a given storage, with file sizes.
pveam remove <storage>:vztmpl/<template>Deletes a downloaded template from disk. Doesn't affect containers already built from it.

One thing worth calling out: removing a template with pveam remove never touches containers you've already created. The template is only used at creation time, to build the container's initial filesystem. After that, the container's data lives on its own storage, completely independent of the template archive.

Common Errors

The template list in the "Create CT" wizard is empty. This almost always means no template has been downloaded to any storage yet — the catalog and the downloaded templates are two different things. Run pveam update then pveam download local <template> to fix it.

A storage doesn't show up as a download target at all. Go back to Datacenter → Storage and check that Container Template is ticked in the Content field for that storage. Block storage like ZFS zvols or LVM-thin won't ever show up here — that's expected, not a misconfiguration.

The download hangs or times out. The Proxmox host needs outbound HTTPS access to reach the template repository. If your host sits behind a proxy or a locked-down firewall, check that outbound traffic on port 443 is actually allowed, and that DNS resolution is working from the host itself, not just from your workstation.

"Storage does not support content-type 'vztmpl'." Same root cause as the missing-storage issue above — the content type just isn't enabled on that storage yet.

Troubleshooting

If pveam update runs without errors but pveam available still shows nothing, check the cached catalog file directly:

ls -la /var/lib/pve-manager/apl-info/

You should see a file in there with content in it. If it's zero bytes or missing, the update genuinely failed silently — usually a DNS or connectivity problem — and it's worth testing basic connectivity from the host with something like ping download.proxmox.com.

If downloads work but new templates never appear where you expect them on disk, remember the actual file path. Templates on the default local storage land in /var/lib/vz/template/cache/. If that storage is running low on space, check it with:

df -h /var/lib/vz

This is a more common problem than people expect, because local often also holds your ISOs and backups, and none of those share space with your actual VM disks if you're using a separate storage pool for those. A drive can look like it has plenty of room in one place and be nearly full in another.

And if a specific download consistently fails while others succeed, try the exact template filename again — Proxmox occasionally deprecates older point releases and pulls them from the repository, so a name from an old forum post or tutorial might no longer exist even though a newer version of the same distro does.

Best Practices

Only keep templates around you're actually still deploying from. I'd set a reminder to clean these up every few months — it's a two-minute job with pveam list and a few pveam remove commands, and it's the kind of maintenance that's easy to keep putting off forever.

Stick to the standard, non-turnkey templates unless you have a specific reason not to. Turnkey appliances are convenient, but they bundle a lot of pre-installed software you probably don't need for a homelab container, and they update less frequently than the plain distro base images.

If you manage more than a couple of Proxmox nodes, download templates once and copy them across nodes over SSH or shared storage rather than re-downloading the same file to each host individually. It's a small thing, but it adds up when you're rebuilding containers regularly.

Match the template's OS version to what you're actually comfortable administering. Grabbing the newest release just because it's at the top of the list isn't always the right call — an LTS release with a longer support window is usually the safer default for anything you plan to keep running.

Frequently Asked Questions

Do I need to run pveam update every time I create a container?

No. Only run it when you want to see newly released templates or the list looks stale. Proxmox refreshes it automatically once a day on its own.

Can I upload my own custom template instead of downloading one?

Yes. You can build your own .tar.zst or .tar.gz rootfs archive and upload it through the storage's Content view, or place it directly in the template folder on disk. Proxmox will list it alongside the official ones as long as it's in the right format and location.

Why is my downloaded template so much smaller than a full VM disk?

Because it's just a compressed root filesystem, not a full disk image with a bootloader and partition table. LXC containers use the host's kernel directly, so there's no kernel, bootloader, or empty free space baked into the archive.

What happens if I delete a template a running container was built from?

Nothing happens to the container. The template is only read once, at creation time. You can safely remove it afterward — you'll just need to download it again if you want to create another container from that same base later.

Why can't I see any templates on my ZFS or Ceph storage?

Those are block-based storage types, and templates need a storage type that stores individual files, like directory storage, NFS, or CIFS. Keep your templates on local or another file-based storage, and put your actual container disks on the faster block storage — that split is normal and how most Proxmox setups are laid out anyway.

Conclusion

None of this is complicated once you've seen it laid out — that's kind of the problem. Most people hit an empty template dropdown, click around for a minute, get frustrated, and never learn what pveam is actually doing behind the "Create CT" wizard. Now you know the catalog and the downloaded files are separate things, why a storage might not qualify as a template target, and where those archives actually live on disk when something needs cleaning up.

Next time a fresh node's template list comes up empty, you won't need to search for the fix — you'll already know it's just pveam update away.