VirtualMemoryStat

Overview

The VirtualMemoryStat struct contains comprehensive RAM usage statistics. The Total, Available, and Used fields provide human-consumable byte counts that work consistently across all platforms. Additional fields contain platform-specific kernel values.

Struct Definition

type VirtualMemoryStat struct {
    // Total amount of RAM on this system
    Total uint64 `json:"total"`

    // RAM available for programs to allocate
    // This value is computed from the kernel specific values.
    Available uint64 `json:"available"`

    // RAM used by programs
    // This value is computed from the kernel specific values.
    Used uint64 `json:"used"`

    // Percentage of RAM used by programs
    // This value is computed from the kernel specific values.
    UsedPercent float64 `json:"usedPercent"`

    // This is the kernel's notion of free memory; RAM chips whose bits nobody
    // cares about the value of right now. For a human consumable number,
    // Available is what you really want.
    Free uint64 `json:"free"`

    // OS X / BSD specific numbers
    Active   uint64 `json:"active"`
    Inactive uint64 `json:"inactive"`
    Wired    uint64 `json:"wired"`

    // FreeBSD specific numbers
    Laundry uint64 `json:"laundry"`

    // Linux specific numbers
    Buffers        uint64 `json:"buffers"`
    Cached         uint64 `json:"cached"`
    WriteBack      uint64 `json:"writeBack"`
    Dirty          uint64 `json:"dirty"`
    WriteBackTmp   uint64 `json:"writeBackTmp"`
    Shared         uint64 `json:"shared"`
    Slab           uint64 `json:"slab"`
    Sreclaimable   uint64 `json:"sreclaimable"`
    Sunreclaim     uint64 `json:"sunreclaim"`
    PageTables     uint64 `json:"pageTables"`
    SwapCached     uint64 `json:"swapCached"`
    CommitLimit    uint64 `json:"commitLimit"`
    CommittedAS    uint64 `json:"committedAS"`
    HighTotal      uint64 `json:"highTotal"`
    HighFree       uint64 `json:"highFree"`
    LowTotal       uint64 `json:"lowTotal"`
    LowFree        uint64 `json:"lowFree"`
    SwapTotal      uint64 `json:"swapTotal"`
    SwapFree       uint64 `json:"swapFree"`
    Mapped         uint64 `json:"mapped"`
    VmallocTotal   uint64 `json:"vmallocTotal"`
    VmallocUsed    uint64 `json:"vmallocUsed"`
    VmallocChunk   uint64 `json:"vmallocChunk"`
    HugePagesTotal uint64 `json:"hugePagesTotal"`
    HugePagesFree  uint64 `json:"hugePagesFree"`
    HugePagesRsvd  uint64 `json:"hugePagesRsvd"`
    HugePagesSurp  uint64 `json:"hugePagesSurp"`
    HugePageSize   uint64 `json:"hugePageSize"`
    AnonHugePages  uint64 `json:"anonHugePages"`
}

Fields

Cross-Platform Fields

These fields are available and meaningful on all supported platforms.

Total

Type: uint64
Description: Total amount of physical RAM installed on the system in bytes
Example: 16777216000 (16 GB)

Available

Type: uint64
Description: RAM available for programs to allocate. This is the best estimate of memory that can be used without swapping
Computed from: Platform-specific kernel values
Use case: Use this to determine if the system has enough memory for new processes

Used

Type: uint64
Description: RAM currently in use by programs
Computed from: Platform-specific kernel values
Note: Does not include all memory, as some may be reclaimable (like caches)

UsedPercent

Type: float64
Description: Percentage of RAM in use (0.0 to 100.0)
Computed from: Platform-specific kernel values
Example: 67.5 means 67.5% of RAM is in use

Free

Type: uint64
Description: Kernel’s notion of completely free memory (unused RAM chips)
Important: This is NOT the amount of memory available for use. Use Available instead for human consumption
Note: On modern systems, this value is often very low because the kernel uses free memory for caching

macOS / BSD Specific Fields

These fields are populated on macOS and BSD systems, zero on other platforms.

Active

Type: uint64
Description: Memory recently accessed and likely to be accessed again
Platform: macOS, FreeBSD, OpenBSD
Reference: Mac memory types

Inactive

Type: uint64
Description: Memory not recently used but still retained in RAM (can be quickly paged back in)
Platform: macOS, FreeBSD, OpenBSD

Wired

Type: uint64
Description: Memory that must stay in RAM and cannot be paged out (kernel code, core system structures)
Platform: macOS, FreeBSD, OpenBSD

FreeBSD Specific Fields

Laundry

Type: uint64
Description: Memory in the laundry queue waiting to be cleaned (dirty pages to be written out)
Platform: FreeBSD only
Reference: FreeBSD patch D8467

Linux Specific Fields

These fields are populated on Linux systems, zero on other platforms. Values typically come from /proc/meminfo.

Buffers

Type: uint64
Description: Memory used for file buffers
Source: /proc/meminfo Buffers field

Cached

Type: uint64
Description: Memory used for page cache and slabs that can be reclaimed
Source: /proc/meminfo Cached field

WriteBack

Type: uint64
Description: Memory waiting to be written back to disk
Source: /proc/meminfo Writeback field

Dirty

Type: uint64
Description: Memory waiting to be written to disk (modified pages)
Source: /proc/meminfo Dirty field

WriteBackTmp

Type: uint64
Description: Temporary writeback memory (FUSE filesystems)
Source: /proc/meminfo WritebackTmp field

Shared

Type: uint64
Description: Memory used by shared memory segments (tmpfs, shared libraries)
Source: /proc/meminfo Shmem field

Slab

Type: uint64
Description: In-kernel data structures cache
Source: /proc/meminfo Slab field

Sreclaimable

Type: uint64
Description: Part of Slab that can be reclaimed (caches)
Source: /proc/meminfo SReclaimable field

Sunreclaim

Type: uint64
Description: Part of Slab that cannot be reclaimed
Source: /proc/meminfo SUnreclaim field

PageTables

Type: uint64
Description: Memory used by page tables
Source: /proc/meminfo PageTables field

SwapCached

Type: uint64
Description: Memory that was swapped out but is now back in RAM (but still also in swap)
Source: /proc/meminfo SwapCached field

CommitLimit

Type: uint64
Description: Total memory that can be allocated, based on overcommit settings
Source: /proc/meminfo CommitLimit field
Reference: Overcommit accounting

CommittedAS

Type: uint64
Description: Amount of memory presently allocated on the system (committed)
Source: /proc/meminfo Committed_AS field
Note: Can exceed physical RAM due to overcommit

HighTotal

Type: uint64
Description: Total high memory (above ~860MB on 32-bit systems)
Source: /proc/meminfo HighTotal field
Note: Only relevant on 32-bit systems

HighFree

Type: uint64
Description: Free high memory
Source: /proc/meminfo HighFree field

LowTotal

Type: uint64
Description: Total low memory (below ~860MB on 32-bit systems)
Source: /proc/meminfo LowTotal field

LowFree

Type: uint64
Description: Free low memory
Source: /proc/meminfo LowFree field

SwapTotal

Type: uint64
Description: Total swap space size
Source: /proc/meminfo SwapTotal field

SwapFree

Type: uint64
Description: Free swap space
Source: /proc/meminfo SwapFree field

Mapped

Type: uint64
Description: Memory mapped files (mmap)
Source: /proc/meminfo Mapped field

VmallocTotal

Type: uint64
Description: Total size of vmalloc memory area
Source: /proc/meminfo VmallocTotal field

VmallocUsed

Type: uint64
Description: Used vmalloc area
Source: /proc/meminfo VmallocUsed field

VmallocChunk

Type: uint64
Description: Largest contiguous block of vmalloc area
Source: /proc/meminfo VmallocChunk field

HugePagesTotal

Type: uint64
Description: Total number of huge pages
Source: /proc/meminfo HugePages_Total field
Reference: Transparent Huge Pages

HugePagesFree

Type: uint64
Description: Free huge pages
Source: /proc/meminfo HugePages_Free field

HugePagesRsvd

Type: uint64
Description: Reserved huge pages
Source: /proc/meminfo HugePages_Rsvd field

HugePagesSurp

Type: uint64
Description: Surplus huge pages
Source: /proc/meminfo HugePages_Surp field

HugePageSize

Type: uint64
Description: Size of one huge page in bytes
Source: /proc/meminfo Hugepagesize field
Typical value: 2097152 (2 MB) or 1073741824 (1 GB)

AnonHugePages

Type: uint64
Description: Anonymous huge pages (non-file backed)
Source: /proc/meminfo AnonHugePages field

Methods

String

func (m VirtualMemoryStat) String() string

Returns a JSON string representation of the struct. Example output:

{
  "total": 16777216000,
  "available": 8388608000,
  "used": 7340032000,
  "usedPercent": 43.75,
  "free": 1048576000,
  "buffers": 524288000,
  "cached": 5242880000
}

Usage Example

package main

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

func main() {
    v, err := mem.VirtualMemory()
    if err != nil {
        log.Fatal(err)
    }

    // Cross-platform fields
    fmt.Printf("Total Memory: %v GB\n", v.Total/1024/1024/1024)
    fmt.Printf("Available Memory: %v GB\n", v.Available/1024/1024/1024)
    fmt.Printf("Used Memory: %v GB\n", v.Used/1024/1024/1024)
    fmt.Printf("Memory Usage: %.2f%%\n", v.UsedPercent)
    
    // Linux specific fields (will be 0 on other platforms)
    if v.Buffers > 0 {
        fmt.Printf("Buffers: %v MB\n", v.Buffers/1024/1024)
    }
    if v.Cached > 0 {
        fmt.Printf("Cached: %v MB\n", v.Cached/1024/1024)
    }
    
    // JSON output
    fmt.Println(v.String())
}

Platform References

Linux Memory Stats

Kernel documentation for /proc/meminfo

Linux Overcommit

Virtual memory overcommit accounting

Transparent Huge Pages

Linux transparent huge pages documentation

macOS Memory Types

Understanding macOS memory categories

Packages

CPU

Memory

Disk

Host

Process

Network

Load

Sensors

Docker

Windows Services

​Overview

​Struct Definition

​Fields

​Cross-Platform Fields

​Total

​Available

​Used

​UsedPercent

​Free

​macOS / BSD Specific Fields

​Active

​Inactive

​Wired

​FreeBSD Specific Fields

​Laundry

​Linux Specific Fields

​Buffers

​Cached

​WriteBack

​Dirty

​WriteBackTmp

​Shared

​Slab

​Sreclaimable

​Sunreclaim

​PageTables

​SwapCached

​CommitLimit

​CommittedAS

​HighTotal

​HighFree

​LowTotal

​LowFree

​SwapTotal

​SwapFree

​Mapped

​VmallocTotal

​VmallocUsed

​VmallocChunk

​HugePagesTotal

​HugePagesFree

​HugePagesRsvd

​HugePagesSurp

​HugePageSize

​AnonHugePages

​Methods

​String

​Usage Example

​Platform References