Skip to main content

​
Introduction

The disk package provides cross-platform access to disk and filesystem information, including disk usage statistics, partition details, and I/O counters. It abstracts platform-specific differences to provide a consistent API across Linux, Windows, macOS, BSD, and other Unix systems.

​
Key Features

Disk Usage

Get filesystem usage statistics including total, used, free space and inode information

Partition Info

List all disk partitions with mount points, filesystem types, and mount options

I/O Counters

Track disk I/O statistics including read/write operations, bytes, and timing

Device Metadata

Retrieve disk serial numbers and labels for device identification

​
Package Import

import "github.com/shirou/gopsutil/v4/disk"

​
Main Functions

​
Usage

Returns filesystem usage statistics for a given path. 
func Usage(path string) (*UsageStat, error)
func UsageWithContext(ctx context.Context, path string) (*UsageStat, error)
Parameters:
  • path - Filesystem path (e.g., /, /home, C:\) - NOT a device path like /dev/sda1
Returns: *UsageStat with space and inode statistics Example: 
usage, err := disk.Usage("/")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Total: %v GB\n", usage.Total/1024/1024/1024)
fmt.Printf("Free: %v GB\n", usage.Free/1024/1024/1024)
fmt.Printf("Used: %.2f%%\n", usage.UsedPercent)

​
Partitions

Returns a list of disk partitions. 
func Partitions(all bool) ([]PartitionStat, error)
func PartitionsWithContext(ctx context.Context, all bool) ([]PartitionStat, error)
Parameters:
  • all - If false, returns only physical devices (hard disks, USB). If true, includes virtual filesystems (tmpfs, devfs, etc.)
  • Note: The all parameter is ignored on BSD systems
Returns: Slice of PartitionStat with partition information Example: 
partitions, err := disk.Partitions(false)
if err != nil {
    log.Fatal(err)
}

for _, partition := range partitions {
    fmt.Printf("Device: %s\n", partition.Device)
    fmt.Printf("  Mountpoint: %s\n", partition.Mountpoint)
    fmt.Printf("  Filesystem: %s\n", partition.Fstype)
    fmt.Printf("  Options: %v\n", partition.Opts)
}

​
IOCounters

Returns I/O statistics for disk devices. 
func IOCounters(names ...string) (map[string]IOCountersStat, error)
func IOCountersWithContext(ctx context.Context, names ...string) (map[string]IOCountersStat, error)
Parameters:
  • names - Optional list of device names to query (e.g., "sda", "sdb"). If empty, returns all devices
Returns: Map of device name to IOCountersStat Example: 
io, err := disk.IOCounters()
if err != nil {
    log.Fatal(err)
}

for name, counters := range io {
    fmt.Printf("Device: %s\n", name)
    fmt.Printf("  Reads: %v\n", counters.ReadCount)
    fmt.Printf("  Writes: %v\n", counters.WriteCount)
    fmt.Printf("  Read Bytes: %v MB\n", counters.ReadBytes/1024/1024)
    fmt.Printf("  Write Bytes: %v MB\n", counters.WriteBytes/1024/1024)
}

​
SerialNumber

Returns the serial number of a disk device. 
func SerialNumber(name string) (string, error)
func SerialNumberWithContext(ctx context.Context, name string) (string, error)
Parameters:
  • name - Device name (e.g., /dev/sda, \\.\PhysicalDrive0)
Returns: Serial number string, or empty string on error Example: 
serial, err := disk.SerialNumber("/dev/sda")
if err != nil {
    log.Printf("Error: %v", err)
} else if serial != "" {
    fmt.Printf("Serial Number: %s\n", serial)
}

​
Label

Returns the label of a disk device. 
func Label(name string) (string, error)
func LabelWithContext(ctx context.Context, name string) (string, error)
Parameters:
  • name - Device name (e.g., /dev/sda)
Returns: Device label string, or empty string on error Note: Supports labels based on device mapper names on Linux Example: 
label, err := disk.Label("/dev/sda1")
if err != nil {
    log.Printf("Error: %v", err)
} else if label != "" {
    fmt.Printf("Label: %s\n", label)
}

​
Data Types

​
Common Use Cases

​
Monitoring Disk Space

package main

import (
    "fmt"
    "log"
    
    "github.com/shirou/gopsutil/v4/disk"
)

func main() {
    // Get all physical partitions
    partitions, err := disk.Partitions(false)
    if err != nil {
        log.Fatal(err)
    }

    // Check usage for each partition
    for _, partition := range partitions {
        usage, err := disk.Usage(partition.Mountpoint)
        if err != nil {
            log.Printf("Error getting usage for %s: %v", partition.Mountpoint, err)
            continue
        }

        fmt.Printf("%s (%s):\n", partition.Mountpoint, partition.Device)
        fmt.Printf("  Total: %v GB\n", usage.Total/1024/1024/1024)
        fmt.Printf("  Used: %v GB (%.2f%%)\n", 
            usage.Used/1024/1024/1024, usage.UsedPercent)
        fmt.Printf("  Free: %v GB\n", usage.Free/1024/1024/1024)
        
        // Alert if usage is high
        if usage.UsedPercent > 90 {
            fmt.Printf("  WARNING: Disk usage critical!\n")
        }
        fmt.Println()
    }
}

​
Monitoring I/O Performance

package main

import (
    "fmt"
    "time"
    
    "github.com/shirou/gopsutil/v4/disk"
)

func main() {
    // Get initial counters
    io1, _ := disk.IOCounters()
    
    time.Sleep(1 * time.Second)
    
    // Get counters after 1 second
    io2, _ := disk.IOCounters()
    
    // Calculate per-second rates
    for name, counters2 := range io2 {
        counters1 := io1[name]
        
        readRate := counters2.ReadBytes - counters1.ReadBytes
        writeRate := counters2.WriteBytes - counters1.WriteBytes
        
        if readRate > 0 || writeRate > 0 {
            fmt.Printf("%s:\n", name)
            fmt.Printf("  Read: %v KB/s\n", readRate/1024)
            fmt.Printf("  Write: %v KB/s\n", writeRate/1024)
        }
    }
}

​
Platform Support

PlatformUsagePartitionsIOCountersSerialNumberLabel
Linux✓✓✓✓✓
Windows✓✓✓✓✓
macOS✓✓✓✓✗
FreeBSD✓✓✓✗✗
OpenBSD✓✓✓✗✗
Solaris✓✓✗✗✗

​
Important Notes

When using disk.Usage(), always pass a filesystem path (like / or /home), not a device path (like /dev/sda1). To use results from disk.Partitions(), use the Mountpoint field, not the Device field.
I/O counters are cumulative since boot. To calculate rates (MB/s, IOPS), you need to sample the counters twice and calculate the delta over the time interval.

Memory Package

Memory and swap statistics

CPU Package

CPU usage and information

Build docs developers (and LLMs) love

Get started for freeTalk to us