gopsutil

gopsutil is a Go port of the popular Python psutil library, exposing operating-system and process metrics through a consistent, idiomatic Go API. It covers CPU usage and info, virtual/swap memory, disk usage and I/O counters, network interfaces and connections, host/platform identification, temperature and battery sensors, load averages, and detailed per-process introspection (CPU time, memory maps, open files, connections, environment, and more).

Everything is implemented without cgo, reading directly from /proc, /sys, sysctl, WMI, or other native OS interfaces depending on platform, which keeps builds simple and fully static. It supports Linux, macOS (Darwin), Windows, FreeBSD, OpenBSD, Solaris, and partial support for DragonFly BSD and AIX, with build-tag-gated files per architecture so each OS gets a native, tested implementation rather than a shared lowest-common-denominator shim.

The project has been actively maintained since 2014, uses CalVer-style tagging (vMAJOR.YY.MM) with monthly releases, and is a foundational dependency for a large swath of the Go observability and infrastructure ecosystem — used inside container runtimes, metrics agents, monitoring tools, and CLI system utilities.

What You Get

• CPU package for per-core and aggregate usage percentages, times, and static CPU info (model, cache size, MHz)
• mem package for virtual memory and swap statistics (total, available, used, cached, dirty, and OS-specific fields)
• disk package for partition listing, usage percentages, and low-level I/O counters (reads, writes, bytes, time)
• net package for interface addresses, IO counters, per-protocol connection listings, and socket-level details
• host package for OS/platform identification, uptime, boot time, users, and temperature/sensor readings
• process package for enumerating processes and querying CPU%, memory maps, open files, connections, and environment per PID
• context-based configuration to override /proc, /sys, /etc paths for containerized or chrooted environments
• optional in-package caching (since v3.24.1) to avoid redundant syscalls on repeated stat calls

Common Use Cases

• Building a metrics/monitoring agent that reports host CPU, memory, disk, and network stats to a time-series backend
• Adding a self-hosted system dashboard or health-check endpoint to a Go service without shelling out to top/ps
• Writing container-aware tooling that reads host stats via HOST_PROC/HOST_SYS environment overrides
• Implementing process supervisors or resource-limit enforcers that need live per-PID CPU/memory/file-descriptor data
• Cross-platform CLI utilities (system-info tools, resource monitors) that need to run identically on Linux, macOS, and Windows

Under The Hood

Architecture gopsutil is organized as one Go package per statistic domain — cpu, mem, disk, net, host, load, sensors, process, plus docker and winservices extras — each exposing a small set of public functions (e.g. mem.VirtualMemory(), cpu.Percent()) that delegate to per-OS files selected at compile time via Go build tags (_linux.go, _darwin.go, _windows.go, _freebsd.go, etc.), with a _fallback.go for unsupported combinations. Shared plumbing — command invocation with timeouts, endian helpers, environment-variable-based path overrides (HOST_PROC, HOST_SYS, HOST_ETC), and warning aggregation — lives in internal/common, consumed by every domain package through an Invoker interface (common.Invoke{}) that call sites can swap out in tests. This keeps the public surface uniform across platforms while letting each OS’s implementation read from its own native source (/proc and /sys on Linux, sysctl on BSD/Darwin, WMI via yusufpapurcu/wmi on Windows) with no shared abstraction leaking platform quirks into callers.

Tech Stack The module targets Go 1.24 and declares zero required dependencies for its core logic beyond small platform helpers: golang.org/x/sys for raw syscalls, github.com/yusufpapurcu/wmi and github.com/go-ole/go-ole for Windows WMI queries, github.com/ebitengine/purego for cgo-free dynamic library calls on Darwin, github.com/tklauser/go-sysconf/numcpus for sysconf-derived values, and github.com/lufia/plan9stats/github.com/power-devops/perfstat for Plan9/AIX-specific stats. github.com/stretchr/testify and github.com/google/go-cmp are dev-only test dependencies. There is no build system beyond go build/go test, plus a Makefile and mktypes.sh for regenerating platform-specific struct bindings from C headers.

Code Quality Testing uses the standard go test runner with testify assertions; the repository ships 43 _test.go files covering most domain packages per platform, including OS-specific test variants (e.g. cpu_darwin_test.go, host_aix_test.go) and a dedicated internal/common/psutiltest helper package. Code style is enforced via a repository-level .golangci.yml linter configuration run in CI (.github/workflows/lint.yml), and build_test.yml/test_freebsd.yml run compilation and tests across the full matrix of supported OS/architecture combinations, plus a dedicated SBOM-generation workflow. Struct fields carry consistent json tags and extensive godoc comments explaining platform-specific meanings (e.g. distinguishing Linux Cached from FreeBSD Laundry), and errors are returned explicitly rather than swallowed, with a shared ErrNotImplementedError/ErrTimeout pair for platform gaps and command timeouts.

What Makes It Unique gopsutil’s core technical bet is doing all of this without cgo: rather than shelling out to system utilities or linking against native C libraries, it parses /proc//sys directly on Linux, calls sysctl via purego on Darwin/BSD without cgo, and issues WMI queries on Windows — keeping consumers’ Go binaries statically linked and simple to cross-compile. Combined with its environment-variable path-override mechanism (HOST_PROC, HOST_SYS, etc.), this makes it a common building block inside containerized monitoring agents that need to observe the host from inside a container, a use case most single-OS or cgo-dependent stats libraries can’t support as cleanly.