Read LVM Volume Group State with vgdisplay

Before you change anything on a volume group, look at it. vgdisplay shows its size, free space and members without any risk of writing metadata.

This guide is a read-only workflow for inspecting LVM volume groups, checking one named group, and producing output that is easier to process in a script. The examples use vgdisplay from LVM2 2.03.16(2), supplied here by Ubuntu package lvm2 2.03.16-3ubuntu3.2.

Allow about ten minutes. You need a shell and the lvm2 package. A normal status check does not need elevated privileges, but device visibility, metadata locks and the host's LVM policy can make an ordinary-user result incomplete. This guide does not create, change, remove or rename a volume group.

1. Confirm the installed command

Start with two read-only checks. They establish which binary and version you are about to use:

$ command -v vgdisplay
/usr/sbin/vgdisplay
$ vgdisplay --version
  LVM version:     2.03.16(2) (2022-05-18)

The version command can also print library and device-mapper diagnostics. Those lines describe the local installation and permissions; they are not volume group data. If the command is missing, install the distribution's lvm2 package before continuing. Do not copy an option from a different LVM version without checking its local help.

Checkpoint: Run vgdisplay --help and confirm that it lists the options used below. The installed command accepts both short and long forms.

2. Display all visible volume groups

Run the command without a volume group name:

$ vgdisplay

For each visible VG, the normal report includes its name, attributes, size and free space, together with associated physical and logical volume information. The exact values are host-specific, so do not compare a pasted report with an example from another machine.

A blank or failed report is not proof that the machine has no LVM. The command only reports groups that its device scan and LVM configuration make visible. Check the exit status immediately if a script or monitoring check depends on the result:

$ vgdisplay
$ status=$?
$ printf 'vgdisplay exit status: %s\n' "$status"
vgdisplay exit status: 0

The zero shown is a successful example, not a promise that every host will return zero. A non-zero status means you should read the diagnostic, check visibility and retry with the appropriate privilege rather than silently treating the result as an empty inventory.

3. Narrow the report to one VG

Pass the exact volume group name as a positional argument. Replace VG_NAME with a name from your own inventory:

$ VG_NAME='data_vg'
$ vgdisplay "$VG_NAME"

Quoting the name is a useful habit even though standard VG names normally avoid whitespace. It keeps the shell from interpreting an unexpected character and makes the placeholder obvious when this command is copied into a wrapper.

Tags can also be supplied in the positional argument area. A tag selects the matching groups rather than identifying one literal name:

$ vgdisplay '@backup'

Use a tag only when you know the host's tagging convention. If a name or tag produces no report, first check its spelling and whether the group is visible to this LVM instance.

4. Use the short form for a quick existence check

If you only need to see whether volume groups exist, use --short:

$ vgdisplay --short
  "data_vg" [active]

The wording and list depend on the groups found on the machine. The point of this mode is a short listing showing VG existence, not a replacement for the detailed report. Treat the output as human-facing unless you have tested its exact format against the installed version.

Checkpoint: If a shell script needs stable fields, move to the reporting mode in the next step instead of scraping labels from the default report.

5. Choose columns for scripts

--columns selects the column report, equivalent to using vgs. You can choose fields with --options; ask the command for the available field names before writing a parser:

$ vgdisplay --columns --options help

For a small report, specify fields that exist in the installed field list:

$ vgdisplay --columns --options vg_name,vg_size,vg_free
  VG      VSize   VFree
  data_vg  1.00t  256.00g

The sample values and alignment are illustrative. Your headings and values depend on the LVM version, configuration and visible groups. For parsing, add --noheadings to remove the heading row and --separator ':' to choose a delimiter:

$ vgdisplay --columns --noheadings --separator ':' --options vg_name,vg_size,vg_free
data_vg:1.00t:256.00g

Do not split on spaces: human-readable sizes and alignment make whitespace a poor delimiter. If suffix-free values are required, combine --nosuffix with --units, and document the unit you selected. Capital letters in --units request SI multiples, while lower-case forms use binary multiples. That distinction is easy to miss.

6. Separate read-only inspection from risky options

vgdisplay is a reporting command, but some common LVM options still deserve care:

--readonly reads on-disk metadata without taking normal locks and avoids communication with the device-mapper driver. It is useful for peeking into metadata, including a virtual machine image, but it cannot report whether logical volumes are actually in use.
--ignorelockingfailure allows read-only metadata operations to continue after locking failures. Do not use it to hide a real concurrent-access problem.
--nolocking disables locking. The manpage warns that concurrent commands can then produce incorrect results. Leave it out for normal administration.
--yes answers prompts affirmatively. It is not needed for this report and should not be added mechanically to copied LVM commands.

None of the examples in this guide changes metadata. There is therefore no undo operation. If you move on to a command such as vgremove, vgreduce or vgchange, stop and make a separate backup and recovery plan first. Those are state-changing operations, not display options.

7. Diagnose missing data and privilege errors

When the report is incomplete, capture the command's diagnostic and status rather than adding random flags:

$ vgdisplay "$VG_NAME" > /tmp/vgdisplay.out 2> /tmp/vgdisplay.err
$ status=$?
$ printf 'status: %s\n' "$status"
$ sed -n '1,40p' /tmp/vgdisplay.err

The temporary files contain local diagnostic output and can be removed after review with rm -- /tmp/vgdisplay.out /tmp/vgdisplay.err. If the error mentions permissions or the device-mapper driver, ask an administrator whether the check should be repeated with sudo vgdisplay. Elevated privileges can improve device access; they do not create a missing VG and should not be used as a first response to a spelling error.

On a host using an LVM devices file, --devicesfile FILE selects a file under /etc/lvm/devices/. The file is managed by lvmdevices, not edited casually. Likewise, --devices PV restricts visible devices and can make existing groups appear incomplete. Remove those restrictions from the diagnostic command unless they are part of the intended inventory policy.

The LVM documentation describes vgs as the preferred alternative when you need a compact and configurable report. Keep vgdisplay for a familiar detailed inspection, and use vgs when its reporting interface better matches an automated check.

Done means

You confirmed the installed vgdisplay binary and LVM2 version.
You can distinguish a visible empty result from a failed device, permission or locking check.
You can select one VG by name or use a known tag.
You use columns, explicit fields, a delimiter and documented units when a script needs structured output.
You understand that --readonly is a specialised inspection mode and that --nolocking is unsafe during concurrent work.
No command in this workflow changed LVM metadata, devices, services or boot configuration.