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.
# old
psutil.virtual_memory()
psutil.swap_memory()
# new
psutil.memory_physical()
psutil.memory_swap()
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¶
cp313t wheels no longer published¶
Free-threaded CPython 3.13 was experimental. Only cp314t wheels are
published.