List all Proxmox VE guests with status and locks (pvesh + jq)

qm list and pct list only show guests on the current node. The API endpoint /cluster/resources returns every guest in the cluster in one call, including fields such as node, status, lock, maxmem, uptime and template. This script reads it with pvesh and formats it as a table.

Requirements

• Run on any node of the cluster, as root or a user allowed to use pvesh. The API only returns guests you have permission to see.
• jq for JSON parsing. It may not be installed by default: apt install jq.

Script

#!/usr/bin/env bash
# pve-guests.sh - list every VM and container in a Proxmox VE cluster
# License: CC0-1.0
# Usage: pve-guests.sh [-r] [-l] [-j]
#   -r  only running guests
#   -l  only guests that currently hold a config lock
#   -j  print raw JSON instead of a table
set -euo pipefail

only_running=0
only_locked=0
raw_json=0

while getopts ":rlj" opt; do
  case "$opt" in
    r) only_running=1 ;;
    l) only_locked=1 ;;
    j) raw_json=1 ;;
    *) echo "Usage: $0 [-r] [-l] [-j]" >&2; exit 2 ;;
  esac
done

for cmd in pvesh jq; do
  if ! command -v "$cmd" >/dev/null 2>&1; then
    echo "Error: '$cmd' not found. Run this on a Proxmox VE node (install jq with: apt install jq)." >&2
    exit 1
  fi
done

json=$(pvesh get /cluster/resources --type vm --output-format json)

filtered=$(jq --argjson running "$only_running" --argjson locked "$only_locked" '
  [ .[]
    | select($running == 0 or .status == "running")
    | select($locked == 0 or ((.lock // "") != ""))
  ] | sort_by(.vmid)
' <<<"$json")

if [ "$raw_json" -eq 1 ]; then
  printf '%s\n' "$filtered"
  exit 0
fi

count=$(jq 'length' <<<"$filtered")
if [ "$count" -eq 0 ]; then
  echo "No matching guests."
  exit 0
fi

printf '%-8s %-5s %-12s %-9s %-10s %8s %10s  %s\n' VMID TYPE NODE STATUS LOCK MEM_MIB UPTIME NAME
jq -r '
  .[] | [
    (.vmid | tostring),
    .type,
    .node,
    .status,
    (if (.lock // "") == "" then "-" else .lock end),
    ((.maxmem // 0) / 1048576 | floor | tostring),
    ((.uptime // 0) as $u
      | if $u == 0 then "-"
        else "\($u / 86400 | floor)d\(($u % 86400) / 3600 | floor)h" end),
    ((.name // "") + (if (.template // 0) == 1 then " (template)" else "" end))
  ] | @tsv
' <<<"$filtered" |
while IFS=$'\t' read -r vmid type node status lock mem uptime name; do
  printf '%-8s %-5s %-12s %-9s %-10s %8s %10s  %s\n' \
    "$vmid" "$type" "$node" "$status" "$lock" "$mem" "$uptime" "$name"
done

echo
jq -r '"\(length) guests: \([.[] | select(.status == "running")] | length) running, \([.[] | select((.lock // "") != "")] | length) locked"' <<<"$filtered"

Usage

chmod +x pve-guests.sh
./pve-guests.sh          # all guests
./pve-guests.sh -r       # running only
./pve-guests.sh -l       # guests with a config lock (backup, migrate, snapshot...)
./pve-guests.sh -j | jq '.[] | select(.node == "pve1") | .vmid'

Example output:

VMID     TYPE  NODE         STATUS    LOCK        MEM_MIB     UPTIME  NAME
100      lxc   pve2         stopped   backup          512          -  dns
101      qemu  pve1         running   -              2048       1d2h  web1
9000     qemu  pve1         stopped   -              2048          -  ubuntu-tpl (template)

3 guests: 1 running, 1 locked

The -l view is handy after an interrupted backup or migration: a lock that stays after its task has finished points to the guests you may need to check (see the entry on VM is locked (backup)).

Official documentation

• pvesh(1): Shell interface for the Proxmox VE API
• Proxmox VE API viewer (/cluster/resources)