How Proxmox Volume IDs Map to Files and Block Storage

A value such as:

local:100/vm-100-disk10.raw

looks partly like a path, but Proxmox VE defines it as a volume identifier: a storage ID followed by a storage-type-dependent volume name, separated by a colon (Proxmox VE Storage).

That distinction determines what the identifier represents. With directory storage, a volume can resolve to a regular file such as /var/lib/vz/images/100/vm-100-disk10.raw. With LVM-thin, the named object is a block volume rather than a file inside an images directory.

The identifier has two parts

Proxmox documents this general form:

<STORAGE_ID>:<storage-type-dependent volume name>

The two parts have different roles:

• Storage ID: the name of a configured Proxmox storage pool
• Volume name: a value interpreted according to that pool’s backend

In the documented example:

local:100/vm-100-disk10.raw

the components are:

Storage ID:  local
Volume name: 100/vm-100-disk10.raw

The right-hand side does not have one universal grammar. Its meaning depends on the storage backend associated with local or any other storage ID (Proxmox VE Storage).

What each storage term identifies

These distinctions help separate Proxmox configuration from filesystem location.

A pool’s content setting selects the supported content types that the pool is intended to hold. Examples include images for QEMU/KVM images, rootdir for container data, iso for ISO images and backup for backup files. It does not specify a particular volume’s physical location (Proxmox VE Storage).

Directory storage: when the volume is a file

The dir backend is file-level storage. Its path property must contain an absolute filesystem path, and Proxmox uses subdirectories beneath that root for different content types (Directory Storage).

The documented default layout includes:

For normal VM image files, the directory backend uses this naming convention:

vm-<VMID>-<NAME>.<FORMAT>

The documented formats are raw, qcow2 and vmdk (Directory Storage).

Proxmox’s example allocates the following volume:

local:100/vm-100-disk10.raw

For the documented local directory storage rooted at /var/lib/vz, that identifier resolves to:

/var/lib/vz/images/100/vm-100-disk10.raw

The components map as follows:

The identifier resembles a path because part of its backend-dependent name helps locate the file. The complete value is still a Proxmox volume identifier, not a literal filesystem pathname.

Why you should not construct the path yourself

Even for directory storage, the example is not a universal formula. A directory pool can use a root other than /var/lib/vz. Its optional content-dirs property can also replace the default content subdirectories with configured relative locations (Directory Storage).

Proxmox documents this command for obtaining the filesystem path associated with a volume identifier:

pvesm path <VOLUME_ID>

For the directory example:

pvesm path local:100/vm-100-disk10.raw

the documented output is:

/var/lib/vz/images/100/vm-100-disk10.raw

Using the documented command avoids relying on assumptions about the pool’s configured root or content layout (Proxmox VE Storage; Directory Storage).

LVM-thin: a named block volume, not a directory file

LVM-thin demonstrates why directory-storage rules cannot be generalized. It is a block-storage backend configured with an LVM volume group and thin-pool name. The documented example is:

lvmthin: local-lvm
        thinpool data
        vgname pve
        content rootdir,images

Its naming convention for normal VM images is:

vm-<VMID>-<NAME>

The two backends therefore represent VM images differently:

LVM-thin supports the raw image format, but its volume naming convention does not use the directory backend’s .raw filename suffix. The LVM-thin documentation also does not place its volumes beneath images/<VMID>/ (LVM-Thin Storage).

The supplied LVM-thin documentation does not show concrete pvesm path output for such a volume, so a device-path form should not be inferred from the volume name.

A practical reading checklist

When interpreting a Proxmox storage value:

1. Split the identifier at the colon.
2. Treat the left side as a configured storage ID, not a path.
3. Check the pool’s backend type.
4. Interpret the right side using that backend’s documented convention.
5. Treat content as a statement of intended content types, not location.
6. For directory storage, account for its configured root and any content-dirs overrides.
7. Use pvesm path <VOLUME_ID> when you need the associated filesystem path rather than deriving one from the identifier.

The central rule is simple: a Proxmox volume ID is a storage-qualified logical identifier. Directory storage can map it to a regular file; LVM-thin identifies a block volume instead. Those examples do not establish naming or path rules for every Proxmox storage backend.

Sources and further reading

• https://pve.proxmox.com/wiki/Storage
• https://pve.proxmox.com/wiki/Storage:_Directory
• https://pve.proxmox.com/wiki/Storage:_LVM_Thin