Skip to main content

​
Overview

gopsutil v4 introduces several breaking changes and new features designed to improve platform compatibility, type safety, and extensibility. This guide provides a comprehensive overview of what’s changed and how to update your code.
v4 contains breaking changes that will require code modifications. Please review this guide carefully before upgrading.

​
What’s New in v4

​
Ex Structs for Platform-Specific Information

v4 introduces a new pattern for accessing platform-specific information through Ex structs. This allows you to access unique platform features while maintaining cross-platform compatibility in the core API.

Ex Structs Documentation

Learn how to use Ex structs to access platform-specific metrics

​
Improved Type Safety

Several functions now use more appropriate types:
  • process.Uids() and process.Gids() now return []uint32 instead of []int32
  • Better alignment with OS-level type definitions

​
Sensors Package

Temperature-related functionality has been moved from the host package to a dedicated sensors package for better organization.

​
Breaking Changes

Import Path Changes: All imports must be updated from v3 to v4

​
Import Path Update

Before (v3): 
import (
    "github.com/shirou/gopsutil/v3/cpu"
    "github.com/shirou/gopsutil/v3/mem"
    "github.com/shirou/gopsutil/v3/host"
)
After (v4): 
import (
    "github.com/shirou/gopsutil/v4/cpu"
    "github.com/shirou/gopsutil/v4/mem"
    "github.com/shirou/gopsutil/v4/sensors"
)

​
Temperature Functions Moved

Breaking: Temperature functions have moved from host to sensors package
Before (v3): 
import "github.com/shirou/gopsutil/v3/host"

temps, err := host.SensorsTemperatures()
After (v4): 
import "github.com/shirou/gopsutil/v4/sensors"

temps, err := sensors.Temperatures()

​
Process UID/GID Type Changes

Breaking: Uids() and Gids() now return []uint32 instead of []int32
Before (v3): 
proc, _ := process.NewProcess(pid)
uids, _ := proc.Uids() // Returns []int32
After (v4): 
proc, _ := process.NewProcess(pid)
uids, _ := proc.Uids() // Returns []uint32
If you were using these values in comparisons or assignments, update your type declarations: 
// Update variable types
var uid uint32 = uids[0]  // Changed from int32

​
New Features

​
Platform-Specific Ex Structs

v4 introduces Ex structs to provide platform-specific information without breaking cross-platform compatibility. These are available in the mem and sensors packages.

​
Linux Example

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

ex := mem.NewExLinux()
v, err := ex.VirtualMemory()
if err != nil {
    panic(err)
}

// Access Linux-specific fields
fmt.Println(v.ActiveFile)
fmt.Println(v.InactiveFile)
fmt.Println(v.ActiveAnon)
fmt.Println(v.Unevictable)

​
Windows Example

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

ex := mem.NewExWindows()
v, err := ex.VirtualMemory()
if err != nil {
    panic(err)
}

// Access Windows-specific fields
fmt.Println(v.VirtualAvail)
fmt.Println(v.VirtualTotal)
fmt.Println(v.CommitLimit)
fmt.Println(v.CommitTotal)

​
Benefits of Ex Structs

  1. Platform-Specific Access: Get detailed metrics unique to each operating system
  2. Type Safety: Platform-specific fields are properly typed
  3. Backward Compatibility: Core API remains cross-platform while Ex provides extensions
  4. Clear Intent: Using Ex makes it explicit that code is platform-specific

​
Minimum Go Version

gopsutil v4 requires Go 1.18 or higher. This allows the use of generics and other modern Go features.
Ensure your project is using Go 1.18+ before upgrading to v4

​
Migration Checklist

1

Update Go version

Ensure you’re using Go 1.18 or higher:
go version
2

Update import paths

Replace all v3 imports with v4:
find . -name '*.go' -exec sed -i 's|github.com/shirou/gopsutil/v3|github.com/shirou/gopsutil/v4|g' {} +
3

Update temperature code

Move host.SensorsTemperatures() calls to sensors.Temperatures()
4

Fix UID/GID types

Update any code using process.Uids() or process.Gids() to handle []uint32
5

Update dependencies

go get -u github.com/shirou/gopsutil/v4
go mod tidy
6

Test thoroughly

Run your test suite to catch any remaining issues:
go test ./...

​
Additional Resources

v3 to v4 Migration

Step-by-step migration instructions

Platform-Specific Features

Learn about Ex structs and platform features

API Reference

Browse the complete v4 API documentation

GitHub Release Notes

View the official v4 release notes

​
Getting Help

If you encounter issues during migration:

Build docs developers (and LLMs) love

Get started for freeTalk to us