Marko Apfel
Proxmox

Managing Proxmox Storage from the Command Line with pvesm

A practical introduction to the Proxmox pvesm command for inspecting and managing storage from the command line.

7 min read

pvesm is the command-line tool Proxmox VE provides for managing its storage subsystem.

While most storage configuration can also be performed through the Proxmox web interface, pvesm is particularly useful when troubleshooting, working over SSH, writing scripts, or simply trying to understand how Proxmox sees its configured storage.

A good starting point is:

pvesm help

For help about a specific command:

pvesm help status

Show configured storage

Probably the most useful pvesm command is:

pvesm status

It displays the storage pools known to the Proxmox host together with their current status and capacity.

Typical output looks roughly like this:

Name           Type     Status     Total        Used       Available    %
local           dir     active     ...
local-lvm     lvmthin   active     ...
nas-backup      nfs     active     ...

This is often the first command to run when investigating storage problems.

For example:

pvesm status

can quickly answer questions such as:

  • Is the storage configured?
  • Is Proxmox able to access it?
  • How much space is available?
  • Which storage backend is being used?

List the contents of a storage

To see volumes stored on a particular storage pool, use:

pvesm list <STORAGE_ID>

For example:

pvesm list local

or:

pvesm list local-lvm

Depending on the storage type, the output may contain virtual-machine disks, container volumes, ISO images, templates, or backups.

A storage identifier is the name shown by:

pvesm status

For example:

local
local-lvm
nas-backup

List volumes belonging to one VM

The output can be restricted to a particular VM or container ID:

pvesm list <STORAGE_ID> --vmid <VMID>

For example:

pvesm list local-lvm --vmid 101

This is especially useful when trying to determine which volumes belong to a particular guest.

For VM 101, you might therefore check several storage pools:

pvesm list local --vmid 101
pvesm list local-lvm --vmid 101
pvesm list nas-storage --vmid 101

List ISO images

Storage contents can also be filtered by content type.

To show ISO images:

pvesm list local --content iso

This is useful on the default local storage, where ISO images are commonly stored.

Similarly, container templates can be listed with:

pvesm list local --content vztmpl

Resolve a Proxmox volume to its filesystem path

Proxmox normally identifies volumes using volume IDs rather than traditional filesystem paths.

For example:

local:iso/debian-13.0.0-amd64-netinst.iso

or:

local:101/vm-101-disk-0.qcow2

To determine the underlying path, use:

pvesm path <VOLUME_ID>

For example:

pvesm path local:iso/debian-13.0.0-amd64-netinst.iso

This might return something similar to:

/var/lib/vz/template/iso/debian-13.0.0-amd64-netinst.iso

This command is extremely useful when combining Proxmox commands with ordinary Linux tools such as:

ls
du
cp
file

For example:

du -h "$(pvesm path local:iso/debian-13.0.0-amd64-netinst.iso)"

Understanding volume IDs

A common source of confusion when first using pvesm is that Proxmox frequently works with volume IDs rather than paths.

A volume ID typically has the form:

<STORAGE_ID>:<VOLUME>

For example:

local:iso/debian.iso

or:

local:101/vm-101-disk-0.qcow2

The part before the colon identifies the Proxmox storage:

local

The part after the colon identifies the object within that storage:

iso/debian.iso

This abstraction allows Proxmox to use the same management commands across very different storage technologies such as:

  • directories
  • NFS
  • CIFS
  • LVM
  • LVM-thin
  • ZFS
  • iSCSI
  • Ceph

The physical representation of a volume can therefore be very different depending on its storage backend.

Add storage

pvesm can also modify the Proxmox storage configuration.

The general syntax is:

pvesm add <TYPE> <STORAGE_ID> <OPTIONS>

For example, a directory-based storage can be added with:

pvesm add dir data --path /mnt/data

An NFS storage could look like:

pvesm add nfs nas-storage \
    --server 10.0.0.20 \
    --export /volume1/proxmox \
    --path /mnt/pve/nas-storage

An LVM storage can be added with:

pvesm add lvm vm-storage --vgname vg0

The exact options depend on the storage backend.

Before creating storage from the command line, it is usually worth checking the available options:

pvesm help add

Modify existing storage

Existing storage can be changed with:

pvesm set <STORAGE_ID> <OPTIONS>

For example, storage can be disabled with:

pvesm set nas-storage --disable 1

and enabled again with:

pvesm set nas-storage --disable 0

This can be useful when troubleshooting unavailable network storage.

Other storage properties can also be modified.

For example:

pvesm set local --content iso

The available options depend on the corresponding storage backend.

Remove a storage configuration

A storage configuration can be removed using:

pvesm remove <STORAGE_ID>

For example:

pvesm remove old-nas

An important distinction is that this removes the Proxmox storage configuration.

It does not necessarily delete the underlying data or unmount the underlying filesystem.

This makes pvesm remove fundamentally different from deleting a virtual disk.

Allocate a volume

Volumes can also be created directly through pvesm.

The general syntax is:

pvesm alloc <STORAGE_ID> <VMID> <NAME> <SIZE>

For example:

pvesm alloc local 101 '' 4G

Passing an empty name allows Proxmox to generate a suitable volume name automatically.

For storage types supporting multiple formats, a format can also be specified:

pvesm alloc local 101 '' 20G --format qcow2

Normally, VM disks are created through qm or the Proxmox web interface rather than through pvesm directly, but the command is useful for scripts and low-level administration.

Delete a volume

A volume can be removed using:

pvesm free <VOLUME_ID>

For example:

pvesm free local:101/vm-101-disk-1.qcow2

This command deserves particular attention:

pvesm free destroys the data stored in the volume.

Before executing it, verify the volume carefully:

pvesm path local:101/vm-101-disk-1.qcow2

and, where applicable:

pvesm list local --vmid 101

The free operation should therefore not be confused with:

pvesm remove

The difference is significant:

pvesm remove   -> remove a storage definition
pvesm free     -> destroy a volume

Scan for available storage

Another useful area of pvesm is storage discovery.

The scan command can query storage systems for resources that Proxmox could potentially use.

Start by displaying the supported scan operations:

pvesm help scan

Depending on the backend, this can be useful for discovering resources such as NFS exports, iSCSI targets, LVM volume groups, or ZFS pools.

For example, scanning before configuring network storage is often preferable to manually guessing export or target names.

Inspect the actual Proxmox storage configuration

Although pvesm provides the management interface, the cluster-wide Proxmox storage configuration is stored in:

/etc/pve/storage.cfg

It can be inspected directly:

cat /etc/pve/storage.cfg

For example, a directory storage may look similar to:

dir: local
    path /var/lib/vz
    content iso,vztmpl,backup

An NFS storage might resemble:

nfs: nas-backup
    export /volume1/proxmox
    path /mnt/pve/nas-backup
    server 10.0.0.20
    content backup

Understanding the relationship between:

/etc/pve/storage.cfg

and:

pvesm status

is very helpful when troubleshooting Proxmox storage.

The configuration file describes what should exist, while pvesm status helps show whether Proxmox can actually access it.

A practical troubleshooting workflow

Suppose a VM disk, ISO image, backup target, or NAS storage does not appear to be working.

A useful sequence is:

pvesm status

First verify whether the storage is active.

Then inspect its contents:

pvesm list <STORAGE_ID>

If investigating a particular VM:

pvesm list <STORAGE_ID> --vmid 101

For file-based storage, determine the real path of an interesting volume:

pvesm path <VOLUME_ID>

Finally, inspect the storage configuration:

cat /etc/pve/storage.cfg

For many storage-related Proxmox problems, these few commands already provide most of the information needed to narrow down the cause.

Commands worth remembering

For everyday administration, the most useful pvesm commands are probably:

# Show all configured storage and its status
pvesm status

# List everything on a storage
pvesm list local

# Show volumes belonging to a VM
pvesm list local-lvm --vmid 101

# Show ISO images
pvesm list local --content iso

# Resolve a Proxmox volume ID to a filesystem path
pvesm path <VOLUME_ID>

# Temporarily disable storage
pvesm set <STORAGE_ID> --disable 1

# Enable it again
pvesm set <STORAGE_ID> --disable 0

# Show command help
pvesm help

Of these, the combination I find most useful for diagnostic work is:

pvesm status
pvesm list <STORAGE_ID>
pvesm path <VOLUME_ID>

Together they answer three fundamental questions:

  1. Which storage systems does Proxmox know about?
  2. What does Proxmox see on a particular storage system?
  3. Where is a particular volume actually located?