Migrating to 8.0

8.0 is a major breaking release, which reorganized the process memory APIs and renamed several functions for the sake of consistency. Most of the old names still work as deprecated aliases.

Breaking changes

Important

Do not rely on positional unpacking of named tuples, since fields can be added or reordered. Use attribute access (see Why should I avoid positional unpacking of named tuples?).

cpu_times() field order changed

user, system and idle are now the first 3 fields on all platforms. On Linux, macOS and BSD positional access silently returns the wrong field.

# old
user, nice, system, idle = psutil.cpu_times()[:4]  # wrong field

# new
t = psutil.cpu_times()
user, system, idle = t.user, t.system, t.idle

Process.memory_info() fields changed

Positional unpacking breaks on Linux, macOS, Windows and BSD.

lib and dirty are no longer returned (always 0 since Linux 2.6).

# old (ValueError)
rss, vms, shared, text, lib, data, dirty = p.memory_info()
p.memory_info().dirty  # DeprecationWarning

# new
m = p.memory_info()
m.rss, m.vms, m.shared, m.text, m.data

pfaults and pageins were removed with no aliases. Use Process.page_faults().

# old
m = p.memory_info()
m.pfaults, m.pageins  # AttributeError

# new
f = p.page_faults()
f.minor + f.major, f.major

The working set and pagefile fields were renamed to rss and vms. The *_pool fields moved to Process.memory_extras(), and num_page_faults to Process.page_faults().

# old (DeprecationWarning)
m = p.memory_info()
m.wset, m.peak_wset
m.pagefile, m.private, m.peak_pagefile
m.paged_pool
m.num_page_faults

# new
m = p.memory_info()
m.rss, m.peak_rss
m.vms, m.vms, m.peak_vms
p.memory_extras().paged_pool
sum(p.page_faults())

New peak_rss field.

# old
rss, vms, text, data, stack = p.memory_info()  # ValueError

# new
m = p.memory_info()
m.rss, m.vms, m.text, m.data, m.stack

virtual_memory() has two new fields on Windows

cached and wired were added, so positional unpacking no longer works.

# old (ValueError)
total, available, percent, used, free = psutil.virtual_memory()

# new
m = psutil.virtual_memory()
m.total, m.available, m.percent, m.used, m.free

Process.ionice() returns a named tuple on Windows

It used to return an integer. It now returns (ioclass, value) like on Linux, with value always 0.

# old
p.ionice() == psutil.IOPRIO_NORMAL  # always False

# new
p.ionice().ioclass == psutil.IOPRIO_NORMAL

users() no longer reports "localhost"

The host field used to be "localhost" both when the OS recorded no host and for an X display (":0"). It is now None in the first case and the display name in the second.

# old: now always empty
local = [u for u in psutil.users() if u.host == "localhost"]

# new
local = [u for u in psutil.users() if not u.host or u.host.startswith(":")]

psutil.OSX removed

Deprecated since 5.4.7. Use MACOS instead.

# old
if psutil.OSX:  # AttributeError
    ...

# new
if psutil.MACOS:
    ...

Deprecations

virtual_memory() and swap_memory() are soft deprecated

Use memory_physical() and memory_swap() instead. The old names keep working as soft deprecated aliases, with no warning and no current plans to remove them.

Process.memory_full_info() is deprecated

Use Process.memory_footprint() for uss, pss and swap, and Process.memory_info() for rss, vms and the rest. Process.memory_footprint() is not available on BSD, SunOS and AIX.

# old
m = p.memory_full_info()  # DeprecationWarning
m.rss, m.uss

# new
p.memory_info().rss
p.memory_footprint().uss

Process.num_ctx_switches() is deprecated

Use Process.ctx_switches() instead. Process.as_dict() now returns a ctx_switches key.

# old
p.num_ctx_switches()  # DeprecationWarning
p.as_dict()["num_ctx_switches"]  # KeyError

# new
p.ctx_switches()
p.as_dict()["ctx_switches"]

Process.info is deprecated

Use Process.snapshot instead:

# old
for p in psutil.process_iter(["name", "username"]):
    print(p.info["name"], p.info["username"])  # DeprecationWarning

# new
for p in psutil.process_iter(["name", "username"]):
    print(p.snapshot.name, p.snapshot.username)

process_iter(attrs=[]) is deprecated

Use the new Process.attrs instead of an empty list meaning “all”. It’s a frozenset of the attribute names accepted by Process.as_dict() and process_iter().

# old
psutil.process_iter(attrs=[])  # DeprecationWarning
attrs = list(psutil.Process().as_dict().keys())

# new
psutil.process_iter(attrs=psutil.Process.attrs)
attrs = psutil.Process.attrs

# new (all except net_connections)
psutil.process_iter(attrs=psutil.Process.attrs - {"net_connections"})

cpu_times() interrupt renamed to irq on Windows

The old name still works but raises DeprecationWarning.

# old
psutil.cpu_times().interrupt  # DeprecationWarning

# new
psutil.cpu_times().irq

Process.connections() raises FutureWarning

Use Process.net_connections() instead. The old name, deprecated since 6.0 (see Migrating to 6.0), is now reported by default and will be removed in 9.0.

# old
p.connections()  # FutureWarning

# new
p.net_connections()

New APIs

New Process.memory_extras() method

It returns the platform-specific memory metrics which Process.memory_info() doesn’t.

  • Linux: peak_rss, peak_vms, rss_anon, rss_file, rss_shmem, swap_anon, locked.

  • macOS: phys_footprint, peak_phys_footprint.

  • Windows: virtual, peak_virtual, paged_pool, nonpaged_pool, peak_paged_pool, peak_nonpaged_pool.

New set_procfs_path() function

Use it instead of assigning PROCFS_PATH, which still works but leaves internal caches stale. The PSUTIL_PROCFS_PATH environment variable does the same from outside the process.

# old
psutil.PROCFS_PATH = "/host/proc"

# new
psutil.set_procfs_path("/host/proc")

New enum classes for constants

They subclass str / int, so existing comparisons keep working.

# old
p.status()            # 'running'
conn.status           # 'LISTEN'
psutil.RLIMIT_NOFILE  # 7

# new
p.status()            # <ProcessStatus.STATUS_RUNNING: 'running'>
conn.status           # <ConnectionStatus.CONN_LISTEN: 'LISTEN'>
psutil.RLIMIT_NOFILE  # <ProcessRlimit.RLIMIT_NOFILE: 7>

Dropped platforms

Python 3.6 and 3.7 dropped

The last supporting release is 7.2.x:

pip install "psutil==7.2.*"

Windows < 10 dropped

The minimum version is now Windows 10 / Windows Server 2016.

macOS 10.7 and 10.8 dropped

The minimum version is now macOS 10.9.

PyPy < 7.3.14 dropped on Windows

The last supporting release is 7.2.x.

Other changes

Git tags renamed

From release-X.Y.Z to vX.Y.Z. The old tags are still there.

# old
pip install git+https://github.com/giampaolo/psutil@release-7.2.2

# new
pip install git+https://github.com/giampaolo/psutil@v7.2.2

cp313t wheels no longer published

Free-threaded CPython 3.13 was experimental. Only cp314t wheels are published.