lsdsk

English | Deutsch

lsdsk is a storage diagnostic for Linux and Windows. It groups every drive under the controller and the PCIe or USB path it hangs off, reads what the ports and the drives can do and what they actually negotiated, reads SMART data and error counters, and recommends what to act on.

USB drives are covered like internal ones. lsdsk shows the speed a USB disk runs at against what the drive and its socket can do, flags a USB 3 drive that came up at USB 2 speed, and reads SMART through the USB bridge where the bridge passes it on. For every disk it shows whether the machine boots from it and what it is mapped to: the drive letters on Windows, the mount points on Linux, or the ZFS pool, LVM volume group, RAID array or encrypted volume it belongs to. FINDINGS.md says exactly when it can call a disk not mounted and when it falls back to - instead.

c't Magazin covered it on 17 September 2026, in German: Kommandozeilentool lsdsk: Performance-Engpässe bei SSDs und Controllern finden.

Ten drives, three controllers, a chipset and a riser between them and the CPU. The machine boots fine, and nothing on it tells you that one card negotiated x1 in an x8 slot, that two SSDs share a link, or that the free port you were about to fill hangs off an uplink that is already full. A storage server rarely fails outright. It runs quietly for years with a shortfall that is easy to fix, and the values that would explain it are spread across sysfs, a set of ioctls and the mainboard manual.

lsdsk starts no subprocesses and makes no network requests - the one exception is the optional Graylog log sink, which stays off unless you enable it. Every value it prints was read directly, from sysfs and direct ioctls on Linux and from SetupAPI and DeviceIoControl on Windows.

QUICKSTART

The command below needs uv and nothing else; if uv is not installed yet, INSTALL.md documents the one-line installer for Linux, macOS and Windows.

For full information run lsdsk as root or Administrator. Without those rights you lose SMART wear, the error counters, PCIe connector detection, the SATA controllers' port count and, on Linux before kernel 6.9, what a USB disk itself can do. The details are in INSTALL.md.

The usual invocation is uvx lsdsk@latest - uv then installs the newest version in a virtual environment. The rest of this document writes the short form lsdsk for readability.

# run as Administrator or root for full information 
uvx lsdsk@latest          # lsdsk TUI
uvx lsdsk@latest report   # get a printed report
uvx lsdsk@latest --help   # get further help

uvx lsdsk@latest opens an interactive view at a terminal, with a page per topic; piped or redirected it prints the same data as one page: the mainboard, what is wrong, the controller tree, every disk's identity, how full each filesystem is, wear and error counters, every SMART attribute, the PCIe slots, and each finding with its reasoning.

The TUI

Number keys switch between the pages, Tab cycles, and every page is also a subcommand, so lsdsk health prints exactly what page 4 shows.

Seven of the nine pages carry a cursor, and a panel under the table gives the detail: every value the row had no column for, and the findings that go with it. PAGES.md describes all nine pages in detail.

Through a pipe, into a file, or with the command lsdsk report, the program prints text instead, most important findings first. REPORT.md documents that report.

Privileges

lsdsk runs unprivileged too. Topology, PCIe link state, SATA capability and negotiated speed, SAS phy rates, a USB disk's link, capacity, controller firmware and NVMe temperature all read without elevated rights.

Five things do need root or Administrator:

• SMART attributes and wear.
• The error counters, so trend and record.
• PCIe slot numbers and whether a port is a real connector.
• The AHCI capability register.
• On Linux before kernel 6.9, what a USB disk itself can do.

Inside an LXC or Proxmox container these values cannot be read even with elevated rights.

lsdsk ships a skill for Claude Code

The hard part of a storage report is not reading it, it is knowing which findings deserve action. lsdsk ships that judgement as a Claude Code skill, so an agent reading the output reaches the same conclusions a practised admin would.

# in claude code
/plugin marketplace add bitranox/lsdsk
/plugin install lsdsk

The skill shows and explains what the tool cannot: that a CRC count is the cable and never the drive, that a wear percentage means nothing without the drive's own threshold, that a controller capped by the board has two opposite remedies depending on whether a faster port exists and is merely occupied, and that a slot number is matched against the mainboard manual because no readable source gives the form factor. lsdsk can also export every value as JSON, and the skill can then interpret that data on another machine. Nobody wants an agent running on the server itself.

Install

uvx lsdsk@latest       # run without installing
uv tool install lsdsk  # install for repeated use, in its own venv
pip install lsdsk      # if you prefer the old way

Python 3.11 or newer, Linux or Windows. It shells out to nothing: no smartmontools, no nvme-cli, no lspci, no subprocess of any kind, and no network access unless you enable the optional Graylog log sink. Its own Python dependencies are declared in pyproject.toml.

From the hardware lsdsk reads only a controller's numeric identifiers, not its name. The PCI name database therefore ships with it. That is why a controller reads the same on Linux and on Windows; lsdsk does not quote the localised device names Windows carries. See NOTICE for that database's licence.

Why we recommend uv: supply-chain protection

This repository commits a uv.lock that pins every dependency, transitive ones included, to an exact version and to the hashes of its files, with a cooldown that keeps releases younger than it out of the lock. CI installs from that lock. A plain pip install takes the newest release of every dependency instead, so a release hijacked an hour earlier reaches you. INSTALL.md shows how to install with a cooldown of your own, or run the exact tree CI tests.

How lsdsk works

Linux reads sysfs and issues SG_IO ATA passthrough and NVMe admin ioctls directly. A SATA port's own speed comes from the AHCI controller's capability register. A USB disk's link comes from sysfs, and on a kernel before 6.9 the drive's own capability from a descriptor request through usbfs. Windows uses SetupAPI and DeviceIoControl through ctypes, with no WMI and no PowerShell, and reads a USB disk's link from its parent hub's port queries. Both platforms receive the same ATA IDENTIFY, ATA SMART and NVMe structures, so a single set of decoders serves both and is tested against captures from real hardware on every supported operating system.

Every command lsdsk issues is a read. It never writes to a device or a controller.

Documentation

Licence

MIT.