psutil documentation
Quick links
About
psutil (python system and process utilities) is a cross-platform library for retrieving information on running processes and system utilization (CPU, memory, disks, network, sensors) in Python. It is useful mainly for system monitoring, profiling, limiting process resources and the management of running processes. It implements many functionalities offered by UNIX command line tools such as: ps, top, lsof, netstat, ifconfig, who, df, kill, free, nice, ionice, iostat, iotop, uptime, pidof, tty, taskset, pmap. psutil currently supports the following platforms:
Linux
Windows
macOS
FreeBSD, OpenBSD, NetBSD
Sun Solaris
AIX
Supported Python versions are 2.7 and 3.6+. PyPy is also known to work.
The psutil documentation you’re reading is distributed as a single HTML page.
Funding
While psutil is free software and will always be, the project would benefit immensely from some funding. Keeping up with bug reports and maintenance has become hardly sustainable for me alone in terms of time. If you’re a company that’s making significant use of psutil you can consider becoming a sponsor via GitHub, Open Collective or PayPal and have your logo displayed in here and psutil doc.
Sponsors
add your logo
Supporters
add your avatar
Install
On Linux, Windows, macOS:
pip install psutil
For other platforms see more detailed install instructions.
Processes
Functions
- psutil.pids()
Return a sorted list of current running PIDs. To iterate over all processes and avoid race conditions
process_iter()
should be preferred.>>> import psutil >>> psutil.pids() [1, 2, 3, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 17, 18, 19, ..., 32498]
Changed in version 5.6.0: PIDs are returned in sorted order
- psutil.process_iter(attrs=None, ad_value=None)
Return an iterator yielding a
Process
class instance for all running processes on the local machine. This should be preferred overpsutil.pids()
to iterate over processes, as retrieving info is safe from race conditions.Every
Process
instance is only created once, and then cached for the next timepsutil.process_iter()
is called (if PID is still alive). Cache can optionally be cleared viaprocess_iter.clear_cache()
.attrs and ad_value have the same meaning as in
Process.as_dict()
. If attrs is specifiedProcess.as_dict()
result will be stored as ainfo
attribute attached to the returnedProcess
instances. If attrs is an empty list it will retrieve all process info (slow).Sorting order in which processes are returned is based on their PID.
Example:
>>> import psutil >>> for proc in psutil.process_iter(['pid', 'name', 'username']): ... print(proc.info) ... {'name': 'systemd', 'pid': 1, 'username': 'root'} {'name': 'kthreadd', 'pid': 2, 'username': 'root'} {'name': 'ksoftirqd/0', 'pid': 3, 'username': 'root'} ...
A dict comprehensions to create a
{pid: info, ...}
data structure:>>> import psutil >>> procs = {p.pid: p.info for p in psutil.process_iter(['name', 'username'])} >>> procs {1: {'name': 'systemd', 'username': 'root'}, 2: {'name': 'kthreadd', 'username': 'root'}, 3: {'name': 'ksoftirqd/0', 'username': 'root'}, ...}
Clear internal cache:
>>> psutil.process_iter.cache_clear()
Changed in version 5.3.0: added “attrs” and “ad_value” parameters.
Changed in version 6.0.0: no longer checks whether each yielded process PID has been reused.
Changed in version 6.0.0: added
psutil.process_iter.cache_clear()
API.
- psutil.pid_exists(pid)
Check whether the given PID exists in the current process list. This is faster than doing
pid in psutil.pids()
and should be preferred.
- psutil.wait_procs(procs, timeout=None, callback=None)
Convenience function which waits for a list of
Process
instances to terminate. Return a(gone, alive)
tuple indicating which processes are gone and which ones are still alive. The gone ones will have a new returncode attribute indicating process exit status as returned byProcess.wait()
.callback
is a function which gets called when one of the processes being waited on is terminated and aProcess
instance is passed as callback argument (the instance will also have a returncode attribute set). This function will return as soon as all processes terminate or when timeout (seconds) occurs. Differently fromProcess.wait()
it will not raiseTimeoutExpired
if timeout occurs. A typical use case may be:send SIGTERM to a list of processes
give them some time to terminate
send SIGKILL to those ones which are still alive
Example which terminates and waits all the children of this process:
import psutil def on_terminate(proc): print("process {} terminated with exit code {}".format(proc, proc.returncode)) procs = psutil.Process().children() for p in procs: p.terminate() gone, alive = psutil.wait_procs(procs, timeout=3, callback=on_terminate) for p in alive: p.kill()
Exceptions
- class psutil.Error
Base exception class. All other exceptions inherit from this one.
- class psutil.NoSuchProcess(pid, name=None, msg=None)
Raised by
Process
class methods when no process with the given pid is found in the current process list, or when a process no longer exists. name is the name the process had before disappearing and gets set only ifProcess.name()
was previously called.
- class psutil.ZombieProcess(pid, name=None, ppid=None, msg=None)
This may be raised by
Process
class methods when querying a zombie process on UNIX (Windows doesn’t have zombie processes). name and ppid attributes are available ifProcess.name()
orProcess.ppid()
methods were called before the process turned into a zombie.Note
this is a subclass of
NoSuchProcess
so if you’re not interested in retrieving zombies (e.g. when usingprocess_iter()
) you can ignore this exception and just catchNoSuchProcess
.Added in version 3.0.0.
- class psutil.AccessDenied(pid=None, name=None, msg=None)
Raised by
Process
class methods when permission to perform an action is denied due to insufficient privileges. name attribute is available ifProcess.name()
was previously called.
- class psutil.TimeoutExpired(seconds, pid=None, name=None, msg=None)
Raised by
Process.wait()
method if timeout expires and the process is still alive. name attribute is available ifProcess.name()
was previously called.
Process class
- class psutil.Process(pid=None)
Represents an OS process with the given pid. If pid is omitted current process pid (os.getpid) is used. Raise
NoSuchProcess
if pid does not exist. On Linux pid can also refer to a thread ID (the id field returned bythreads()
method). When accessing methods of this class always be prepared to catchNoSuchProcess
andAccessDenied
exceptions. hash builtin can be used against instances of this class in order to identify a process univocally over time (the hash is determined by mixing process PID + creation time). As such it can also be used with set.Note
In order to efficiently fetch more than one information about the process at the same time, make sure to use either
oneshot()
context manager oras_dict()
utility method.Note
the way this class is bound to a process is via its PID. That means that if the process terminates and the OS reuses its PID you may inadvertently end up querying another process. To prevent this problem you can use
is_running()
first. The only methods which preemptively check whether PID has been reused (via PID + creation time) are:nice()
(set),ionice()
(set),cpu_affinity()
(set),rlimit()
(set),children()
,ppid()
,parent()
,parents()
,suspend()
resume()
,send_signal()
,terminate()
andkill()
.- oneshot()
Utility context manager which considerably speeds up the retrieval of multiple process information at the same time. Internally different process info (e.g.
name()
,ppid()
,uids()
,create_time()
, …) may be fetched by using the same routine, but only one value is returned and the others are discarded. When using this context manager the internal routine is executed once (in the example below onname()
) the value of interest is returned and the others are cached. The subsequent calls sharing the same internal routine will return the cached value. The cache is cleared when exiting the context manager block. The advice is to use this every time you retrieve more than one information about the process. If you’re lucky, you’ll get a hell of a speedup. Example:>>> import psutil >>> p = psutil.Process() >>> with p.oneshot(): ... p.name() # execute internal routine once collecting multiple info ... p.cpu_times() # return cached value ... p.cpu_percent() # return cached value ... p.create_time() # return cached value ... p.ppid() # return cached value ... p.status() # return cached value ... >>>
Here’s a list of methods which can take advantage of the speedup depending on what platform you’re on. In the table below horizontal empty rows indicate what process methods can be efficiently grouped together internally. The last column (speedup) shows an approximation of the speedup you can get if you call all the methods together (best case scenario).
Linux
Windows
macOS
BSD
SunOS
AIX
speedup: +2.6x
speedup: +1.8x / +6.5x
speedup: +1.9x
speedup: +2.0x
speedup: +1.3x
speedup: +1.3x
Added in version 5.0.0.
- pid
The process PID. This is the only (read-only) attribute of the class.
- ppid()
The process parent PID. On Windows the return value is cached after first call. Not on POSIX because ppid may change if process becomes a zombie See also
parent()
andparents()
methods.
- name()
The process name. On Windows the return value is cached after first call. Not on POSIX because the process name may change. See also how to find a process by name.
- exe()
The process executable as an absolute path. On some systems, if exe cannot be determined for some internal reason (e.g. system process or path no longer exists), this may be an empty string. The return value is cached after first call.
>>> import psutil >>> psutil.Process().exe() '/usr/bin/python2.7'
- cmdline()
The command line this process has been called with as a list of strings. The return value is not cached because the cmdline of a process may change.
>>> import psutil >>> psutil.Process().cmdline() ['python', 'manage.py', 'runserver']
- environ()
The environment variables of the process as a dict. Note: this might not reflect changes made after the process started.
>>> import psutil >>> psutil.Process().environ() {'LC_NUMERIC': 'it_IT.UTF-8', 'QT_QPA_PLATFORMTHEME': 'appmenu-qt5', 'IM_CONFIG_PHASE': '1', 'XDG_GREETER_DATA_DIR': '/var/lib/lightdm-data/giampaolo', 'XDG_CURRENT_DESKTOP': 'Unity', 'UPSTART_EVENTS': 'started starting', 'GNOME_KEYRING_PID': '', 'XDG_VTNR': '7', 'QT_IM_MODULE': 'ibus', 'LOGNAME': 'giampaolo', 'USER': 'giampaolo', 'PATH': '/home/giampaolo/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/home/giampaolo/svn/sysconf/bin', 'LC_PAPER': 'it_IT.UTF-8', 'GNOME_KEYRING_CONTROL': '', 'GTK_IM_MODULE': 'ibus', 'DISPLAY': ':0', 'LANG': 'en_US.UTF-8', 'LESS_TERMCAP_se': '\x1b[0m', 'TERM': 'xterm-256color', 'SHELL': '/bin/bash', 'XDG_SESSION_PATH': '/org/freedesktop/DisplayManager/Session0', 'XAUTHORITY': '/home/giampaolo/.Xauthority', 'LANGUAGE': 'en_US', 'COMPIZ_CONFIG_PROFILE': 'ubuntu', 'LC_MONETARY': 'it_IT.UTF-8', 'QT_LINUX_ACCESSIBILITY_ALWAYS_ON': '1', 'LESS_TERMCAP_me': '\x1b[0m', 'LESS_TERMCAP_md': '\x1b[01;38;5;74m', 'LESS_TERMCAP_mb': '\x1b[01;31m', 'HISTSIZE': '100000', 'UPSTART_INSTANCE': '', 'CLUTTER_IM_MODULE': 'xim', 'WINDOWID': '58786407', 'EDITOR': 'vim', 'SESSIONTYPE': 'gnome-session', 'XMODIFIERS': '@im=ibus', 'GPG_AGENT_INFO': '/home/giampaolo/.gnupg/S.gpg-agent:0:1', 'HOME': '/home/giampaolo', 'HISTFILESIZE': '100000', 'QT4_IM_MODULE': 'xim', 'GTK2_MODULES': 'overlay-scrollbar', 'XDG_SESSION_DESKTOP': 'ubuntu', 'SHLVL': '1', 'XDG_RUNTIME_DIR': '/run/user/1000', 'INSTANCE': 'Unity', 'LC_ADDRESS': 'it_IT.UTF-8', 'SSH_AUTH_SOCK': '/run/user/1000/keyring/ssh', 'VTE_VERSION': '4205', 'GDMSESSION': 'ubuntu', 'MANDATORY_PATH': '/usr/share/gconf/ubuntu.mandatory.path', 'VISUAL': 'vim', 'DESKTOP_SESSION': 'ubuntu', 'QT_ACCESSIBILITY': '1', 'XDG_SEAT_PATH': '/org/freedesktop/DisplayManager/Seat0', 'LESSCLOSE': '/usr/bin/lesspipe %s %s', 'LESSOPEN': '| /usr/bin/lesspipe %s', 'XDG_SESSION_ID': 'c2', 'DBUS_SESSION_BUS_ADDRESS': 'unix:abstract=/tmp/dbus-9GAJpvnt8r', '_': '/usr/bin/python', 'DEFAULTS_PATH': '/usr/share/gconf/ubuntu.default.path', 'LC_IDENTIFICATION': 'it_IT.UTF-8', 'LESS_TERMCAP_ue': '\x1b[0m', 'UPSTART_SESSION': 'unix:abstract=/com/ubuntu/upstart-session/1000/1294', 'XDG_CONFIG_DIRS': '/etc/xdg/xdg-ubuntu:/usr/share/upstart/xdg:/etc/xdg', 'GTK_MODULES': 'gail:atk-bridge:unity-gtk-module', 'XDG_SESSION_TYPE': 'x11', 'PYTHONSTARTUP': '/home/giampaolo/.pythonstart', 'LC_NAME': 'it_IT.UTF-8', 'OLDPWD': '/home/giampaolo/svn/curio_giampaolo/tests', 'GDM_LANG': 'en_US', 'LC_TELEPHONE': 'it_IT.UTF-8', 'HISTCONTROL': 'ignoredups:erasedups', 'LC_MEASUREMENT': 'it_IT.UTF-8', 'PWD': '/home/giampaolo/svn/curio_giampaolo', 'JOB': 'gnome-session', 'LESS_TERMCAP_us': '\x1b[04;38;5;146m', 'UPSTART_JOB': 'unity-settings-daemon', 'LC_TIME': 'it_IT.UTF-8', 'LESS_TERMCAP_so': '\x1b[38;5;246m', 'PAGER': 'less', 'XDG_DATA_DIRS': '/usr/share/ubuntu:/usr/share/gnome:/usr/local/share/:/usr/share/:/var/lib/snapd/desktop', 'XDG_SEAT': 'seat0'}
Note
on macOS Big Sur this function returns something meaningful only for the current process or in other specific circumstances).
Added in version 4.0.0.
Changed in version 5.3.0: added SunOS support
Changed in version 5.6.3: added AIX support
Changed in version 5.7.3: added BSD support
- create_time()
The process creation time as a floating point number expressed in seconds since the epoch. The return value is cached after first call.
>>> import psutil, datetime >>> p = psutil.Process() >>> p.create_time() 1307289803.47 >>> datetime.datetime.fromtimestamp(p.create_time()).strftime("%Y-%m-%d %H:%M:%S") '2011-03-05 18:03:52'
- as_dict(attrs=None, ad_value=None)
Utility method retrieving multiple process information as a dictionary. If attrs is specified it must be a list of strings reflecting available
Process
class’s attribute names. Here’s a list of possible string values:'cmdline'
,'net_connections'
,'cpu_affinity'
,'cpu_num'
,'cpu_percent'
,'cpu_times'
,'create_time'
,'cwd'
,'environ'
,'exe'
,'gids'
,'io_counters'
,'ionice'
,'memory_full_info'
,'memory_info'
,'memory_maps'
,'memory_percent'
,'name'
,'nice'
,'num_ctx_switches'
,'num_fds'
,'num_handles'
,'num_threads'
,'open_files'
,'pid'
,'ppid'
,'status'
,'terminal'
,'threads'
,'uids'
,'username'`
. If attrs argument is not passed all public read only attributes are assumed. ad_value is the value which gets assigned to a dict key in caseAccessDenied
orZombieProcess
exception is raised when retrieving that particular process information. Internally,as_dict()
usesoneshot()
context manager so there’s no need you use it also.>>> import psutil >>> p = psutil.Process() >>> p.as_dict(attrs=['pid', 'name', 'username']) {'username': 'giampaolo', 'pid': 12366, 'name': 'python'} >>> >>> # get a list of valid attrs names >>> list(psutil.Process().as_dict().keys()) ['cmdline', 'connections', 'cpu_affinity', 'cpu_num', 'cpu_percent', 'cpu_times', 'create_time', 'cwd', 'environ', 'exe', 'gids', 'io_counters', 'ionice', 'memory_full_info', 'memory_info', 'memory_maps', 'memory_percent', 'name', 'net_connections', 'nice', 'num_ctx_switches', 'num_fds', 'num_threads', 'open_files', 'pid', 'ppid', 'status', 'terminal', 'threads', 'uids', 'username']
Changed in version 3.0.0: ad_value is used also when incurring into
ZombieProcess
exception, not onlyAccessDenied
- parent()
Utility method which returns the parent process as a
Process
object, preemptively checking whether PID has been reused. If no parent PID is known returnNone
. See alsoppid()
andparents()
methods.
- parents()
Utility method which return the parents of this process as a list of
Process
instances. If no parents are known return an empty list. See alsoppid()
andparent()
methods.Added in version 5.6.0.
- status()
The current process status as a string. The returned string is one of the psutil.STATUS_* constants.
- cwd()
The process current working directory as an absolute path. If cwd cannot be determined for some internal reason (e.g. system process or directory no longer exists) it may return an empty string.
Changed in version 5.6.4: added support for NetBSD
- username()
The name of the user that owns the process. On UNIX this is calculated by using real process uid.
- uids()
The real, effective and saved user ids of this process as a named tuple. This is the same as os.getresuid but can be used for any process PID.
Availability: UNIX
- gids()
The real, effective and saved group ids of this process as a named tuple. This is the same as os.getresgid but can be used for any process PID.
Availability: UNIX
- terminal()
The terminal associated with this process, if any, else
None
. This is similar to “tty” command but can be used for any process PID.Availability: UNIX
- nice(value=None)
Get or set process niceness (priority). On UNIX this is a number which usually goes from
-20
to20
. The higher the nice value, the lower the priority of the process.>>> import psutil >>> p = psutil.Process() >>> p.nice(10) # set >>> p.nice() # get 10 >>>
Starting from Python 3.3 this functionality is also available as os.getpriority and os.setpriority (see BPO-10784). On Windows this is implemented via GetPriorityClass and SetPriorityClass Windows APIs and value is one of the
psutil.*_PRIORITY_CLASS
constants reflecting the MSDN documentation. Example which increases process priority on Windows:>>> p.nice(psutil.HIGH_PRIORITY_CLASS)
- ionice(ioclass=None, value=None)
Get or set process I/O niceness (priority). If no argument is provided it acts as a get, returning a
(ioclass, value)
tuple on Linux and a ioclass integer on Windows. If ioclass is provided it acts as a set. In this case an additional value can be specified on Linux only in order to increase or decrease the I/O priority even further. Here’s the possible platform-dependent ioclass values.Linux (see ioprio_get manual):
IOPRIO_CLASS_RT
: (high) the process gets first access to the disk every time. Use it with care as it can starve the entire system. Additional priority level can be specified and ranges from0
(highest) to7
(lowest).IOPRIO_CLASS_BE
: (normal) the default for any process that hasn’t set a specific I/O priority. Additional priority level ranges from0
(highest) to7
(lowest).IOPRIO_CLASS_IDLE
: (low) get I/O time when no-one else needs the disk. No additional value is accepted.IOPRIO_CLASS_NONE
: returned when no priority was previously set.
Windows:
IOPRIO_HIGH
: highest priority.IOPRIO_NORMAL
: default priority.IOPRIO_LOW
: low priority.IOPRIO_VERYLOW
: lowest priority.
Here’s an example on how to set the highest I/O priority depending on what platform you’re on:
>>> import psutil >>> p = psutil.Process() >>> if psutil.LINUX: ... p.ionice(psutil.IOPRIO_CLASS_RT, value=7) ... else: ... p.ionice(psutil.IOPRIO_HIGH) ... >>> p.ionice() # get pionice(ioclass=<IOPriority.IOPRIO_CLASS_RT: 1>, value=7)
Availability: Linux, Windows Vista+
Changed in version 5.6.2: Windows accepts new
IOPRIO_*
constants including newIOPRIO_HIGH
.
- rlimit(resource, limits=None)
Get or set process resource limits (see man prlimit). resource is one of the psutil.RLIMIT_* constants. limits is a
(soft, hard)
tuple. This is the same as resource.getrlimit and resource.setrlimit but can be used for any process PID, not only os.getpid. For get, return value is a(soft, hard)
tuple. Each value may be either and integer orpsutil.RLIMIT_*
. Example:>>> import psutil >>> p = psutil.Process() >>> p.rlimit(psutil.RLIMIT_NOFILE, (128, 128)) # process can open max 128 file descriptors >>> p.rlimit(psutil.RLIMIT_FSIZE, (1024, 1024)) # can create files no bigger than 1024 bytes >>> p.rlimit(psutil.RLIMIT_FSIZE) # get (1024, 1024) >>>
Also see procinfo.py script.
Availability: Linux, FreeBSD
Changed in version 5.7.3: added FreeBSD support
- io_counters()
Return process I/O statistics as a named tuple. For Linux you can refer to /proc filesystem documentation.
read_count: the number of read operations performed (cumulative). This is supposed to count the number of read-related syscalls such as
read()
andpread()
on UNIX.write_count: the number of write operations performed (cumulative). This is supposed to count the number of write-related syscalls such as
write()
andpwrite()
on UNIX.read_bytes: the number of bytes read (cumulative). Always
-1
on BSD.write_bytes: the number of bytes written (cumulative). Always
-1
on BSD.
Linux specific:
read_chars (Linux): the amount of bytes which this process passed to
read()
andpread()
syscalls (cumulative). Differently from read_bytes it doesn’t care whether or not actual physical disk I/O occurred.write_chars (Linux): the amount of bytes which this process passed to
write()
andpwrite()
syscalls (cumulative). Differently from write_bytes it doesn’t care whether or not actual physical disk I/O occurred.
Windows specific:
other_count (Windows): the number of I/O operations performed other than read and write operations.
other_bytes (Windows): the number of bytes transferred during operations other than read and write operations.
>>> import psutil >>> p = psutil.Process() >>> p.io_counters() pio(read_count=454556, write_count=3456, read_bytes=110592, write_bytes=0, read_chars=769931, write_chars=203)
Availability: Linux, BSD, Windows, AIX
Changed in version 5.2.0: added read_chars and write_chars on Linux; added other_count and other_bytes on Windows.
- num_ctx_switches()
The number voluntary and involuntary context switches performed by this process (cumulative).
Changed in version 5.4.1: added AIX support
- num_fds()
The number of file descriptors currently opened by this process (non cumulative).
Availability: UNIX
- num_handles()
The number of handles currently used by this process (non cumulative).
Availability: Windows
- num_threads()
The number of threads currently used by this process (non cumulative).
- threads()
Return threads opened by process as a list of named tuples. On OpenBSD this method requires root privileges.
id: the native thread ID assigned by the kernel. If
pid
refers to the current process, this matches the native_id attribute of the threading.Thread class, and can be used to reference individual Python threads running within your own Python app.user_time: time spent in user mode.
system_time: time spent in kernel mode.
- cpu_times()
Return a named tuple representing the accumulated process times, in seconds (see explanation). This is similar to os.times but can be used for any process PID.
user: time spent in user mode.
system: time spent in kernel mode.
children_user: user time of all child processes (always
0
on Windows and macOS).children_system: system time of all child processes (always
0
on Windows and macOS).iowait: (Linux) time spent waiting for blocking I/O to complete. This value is excluded from user and system times count (because the CPU is not doing any work).
>>> import psutil >>> p = psutil.Process() >>> p.cpu_times() pcputimes(user=0.03, system=0.67, children_user=0.0, children_system=0.0, iowait=0.08) >>> sum(p.cpu_times()[:2]) # cumulative, excluding children and iowait 0.70
Changed in version 4.1.0: return two extra fields: children_user and children_system.
Changed in version 5.6.4: added iowait on Linux.
- cpu_percent(interval=None)
Return a float representing the process CPU utilization as a percentage which can also be
> 100.0
in case of a process running multiple threads on different CPUs. When interval is >0.0
compares process times to system CPU times elapsed before and after the interval (blocking). When interval is0.0
orNone
compares process times to system CPU times elapsed since last call, returning immediately. That means the first time this is called it will return a meaningless0.0
value which you are supposed to ignore. In this case is recommended for accuracy that this function be called a second time with at least0.1
seconds between calls. Example:>>> import psutil >>> p = psutil.Process() >>> # blocking >>> p.cpu_percent(interval=1) 2.0 >>> # non-blocking (percentage since last call) >>> p.cpu_percent(interval=None) 2.9
Note
the returned value can be > 100.0 in case of a process running multiple threads on different CPU cores.
Note
the returned value is explicitly not split evenly between all available CPUs (differently from
psutil.cpu_percent()
). This means that a busy loop process running on a system with 2 logical CPUs will be reported as having 100% CPU utilization instead of 50%. This was done in order to be consistent withtop
UNIX utility and also to make it easier to identify processes hogging CPU resources independently from the number of CPUs. It must be noted thattaskmgr.exe
on Windows does not behave like this (it would report 50% usage instead). To emulate Windowstaskmgr.exe
behavior you can do:p.cpu_percent() / psutil.cpu_count()
.Warning
the first time this method is called with interval =
0.0
orNone
it will return a meaningless0.0
value which you are supposed to ignore.
- cpu_affinity(cpus=None)
Get or set process current CPU affinity. CPU affinity consists in telling the OS to run a process on a limited set of CPUs only (on Linux cmdline,
taskset
command is typically used). If no argument is passed it returns the current CPU affinity as a list of integers. If passed it must be a list of integers specifying the new CPUs affinity. If an empty list is passed all eligible CPUs are assumed (and set). On some systems such as Linux this may not necessarily mean all available logical CPUs as inlist(range(psutil.cpu_count()))
).>>> import psutil >>> psutil.cpu_count() 4 >>> p = psutil.Process() >>> # get >>> p.cpu_affinity() [0, 1, 2, 3] >>> # set; from now on, process will run on CPU #0 and #1 only >>> p.cpu_affinity([0, 1]) >>> p.cpu_affinity() [0, 1] >>> # reset affinity against all eligible CPUs >>> p.cpu_affinity([])
Availability: Linux, Windows, FreeBSD
Changed in version 2.2.0: added support for FreeBSD
Changed in version 5.1.0: an empty list can be passed to set affinity against all eligible CPUs.
- cpu_num()
Return what CPU this process is currently running on. The returned number should be
<=
psutil.cpu_count()
. On FreeBSD certain kernel process may return-1
. It may be used in conjunction withpsutil.cpu_percent(percpu=True)
to observe the system workload distributed across multiple CPUs as shown by cpu_distribution.py example script.Availability: Linux, FreeBSD, SunOS
Added in version 5.1.0.
- memory_info()
Return a named tuple with variable fields depending on the platform representing memory information about the process. The “portable” fields available on all platforms are rss and vms. All numbers are expressed in bytes.
Linux
macOS
BSD
Solaris
AIX
Windows
rss
rss
rss
rss
rss
rss (alias for
wset
)vms
vms
vms
vms
vms
vms (alias for
pagefile
)shared
pfaults
text
num_page_faults
text
pageins
data
peak_wset
lib
stack
wset
data
peak_paged_pool
dirty
paged_pool
peak_nonpaged_pool
nonpaged_pool
pagefile
peak_pagefile
private
rss: aka “Resident Set Size”, this is the non-swapped physical memory a process has used. On UNIX it matches “top“‘s RES column). On Windows this is an alias for wset field and it matches “Mem Usage” column of taskmgr.exe.
vms: aka “Virtual Memory Size”, this is the total amount of virtual memory used by the process. On UNIX it matches “top“‘s VIRT column. On Windows this is an alias for pagefile field and it matches “Mem Usage” “VM Size” column of taskmgr.exe.
shared: (Linux) memory that could be potentially shared with other processes. This matches “top“‘s SHR column).
text (Linux, BSD): aka TRS (text resident set) the amount of memory devoted to executable code. This matches “top“‘s CODE column).
data (Linux, BSD): aka DRS (data resident set) the amount of physical memory devoted to other than executable code. It matches “top“‘s DATA column).
lib (Linux): the memory used by shared libraries.
dirty (Linux): the number of dirty pages.
pfaults (macOS): number of page faults.
pageins (macOS): number of actual pageins.
For on explanation of Windows fields rely on PROCESS_MEMORY_COUNTERS_EX structure doc. Example on Linux:
>>> import psutil >>> p = psutil.Process() >>> p.memory_info() pmem(rss=15491072, vms=84025344, shared=5206016, text=2555904, lib=0, data=9891840, dirty=0)
Changed in version 4.0.0: multiple fields are returned, not only rss and vms.
- memory_info_ex()
Same as
memory_info()
(deprecated).Warning
deprecated in version 4.0.0; use
memory_info()
instead.
- memory_full_info()
This method returns the same information as
memory_info()
, plus, on some platform (Linux, macOS, Windows), also provides additional metrics (USS, PSS and swap). The additional metrics provide a better representation of “effective” process memory consumption (in case of USS) as explained in detail in this blog post. It does so by passing through the whole process address. As such it usually requires higher user privileges thanmemory_info()
and is considerably slower. On platforms where extra fields are not implemented this simply returns the same metrics asmemory_info()
.uss (Linux, macOS, Windows): aka “Unique Set Size”, this is the memory which is unique to a process and which would be freed if the process was terminated right now.
pss (Linux): aka “Proportional Set Size”, is the amount of memory shared with other processes, accounted in a way that the amount is divided evenly between the processes that share it. I.e. if a process has 10 MBs all to itself and 10 MBs shared with another process its PSS will be 15 MBs.
swap (Linux): amount of memory that has been swapped out to disk.
Note
uss is probably the most representative metric for determining how much memory is actually being used by a process. It represents the amount of memory that would be freed if the process was terminated right now.
Example on Linux:
>>> import psutil >>> p = psutil.Process() >>> p.memory_full_info() pfullmem(rss=10199040, vms=52133888, shared=3887104, text=2867200, lib=0, data=5967872, dirty=0, uss=6545408, pss=6872064, swap=0) >>>
See also procsmem.py for an example application.
Added in version 4.0.0.
- memory_percent(memtype='rss')
Compare process memory to total physical system memory and calculate process memory utilization as a percentage. memtype argument is a string that dictates what type of process memory you want to compare against. You can choose between the named tuple field names returned by
memory_info()
andmemory_full_info()
(defaults to"rss"
).Changed in version 4.0.0: added memtype parameter.
- memory_maps(grouped=True)
Return process’s mapped memory regions as a list of named tuples whose fields are variable depending on the platform. This method is useful to obtain a detailed representation of process memory usage as explained here (the most important value is “private” memory). If grouped is
True
the mapped regions with the same path are grouped together and the different memory fields are summed. If grouped isFalse
each mapped region is shown as a single entity and the named tuple will also include the mapped region’s address space (addr) and permission set (perms). See pmap.py for an example application.Linux
Windows
FreeBSD
Solaris
rss
rss
rss
rss
size
private
anonymous
pss
ref_count
locked
shared_clean
shadow_count
shared_dirty
private_clean
private_dirty
referenced
anonymous
swap
>>> import psutil >>> p = psutil.Process() >>> p.memory_maps() [pmmap_grouped(path='/lib/x8664-linux-gnu/libutil-2.15.so', rss=32768, size=2125824, pss=32768, shared_clean=0, shared_dirty=0, private_clean=20480, private_dirty=12288, referenced=32768, anonymous=12288, swap=0), pmmap_grouped(path='/lib/x8664-linux-gnu/libc-2.15.so', rss=3821568, size=3842048, pss=3821568, shared_clean=0, shared_dirty=0, private_clean=0, private_dirty=3821568, referenced=3575808, anonymous=3821568, swap=0), ...]
Availability: Linux, Windows, FreeBSD, SunOS
Changed in version 5.6.0: removed macOS support because inherently broken (see issue #1291)
- children(recursive=False)
Return the children of this process as a list of
Process
instances. If recursive is True return all the parent descendants. Pseudo code example assuming A == this process:A ─┐ │ ├─ B (child) ─┐ │ └─ X (grandchild) ─┐ │ └─ Y (great grandchild) ├─ C (child) └─ D (child) >>> p.children() B, C, D >>> p.children(recursive=True) B, X, Y, C, D
Note that in the example above if process X disappears process Y won’t be returned either as the reference to process A is lost. This concept is well summaried by this unit test. See also how to kill a process tree and terminate my children.
- open_files()
Return regular files opened by process as a list of named tuples including the following fields:
path: the absolute file name.
fd: the file descriptor number; on Windows this is always
-1
.
Linux only:
position (Linux): the file (offset) position.
mode (Linux): a string indicating how the file was opened, similarly to open builtin
mode
argument. Possible values are'r'
,'w'
,'a'
,'r+'
and'a+'
. There’s no distinction between files opened in binary or text mode ("b"
or"t"
).flags (Linux): the flags which were passed to the underlying os.open C call when the file was opened (e.g. os.O_RDONLY, os.O_TRUNC, etc).
>>> import psutil >>> f = open('file.ext', 'w') >>> p = psutil.Process() >>> p.open_files() [popenfile(path='/home/giampaolo/svn/psutil/file.ext', fd=3, position=0, mode='w', flags=32769)]
Warning
on Windows this method is not reliable due to some limitations of the underlying Windows API which may hang when retrieving certain file handles. In order to work around that psutil spawns a thread to determine the file handle name and kills it if it’s not responding after 100ms. That implies that this method on Windows is not guaranteed to enumerate all regular file handles (see issue 597). Tools like ProcessHacker has the same limitation.
Warning
on BSD this method can return files with a null path (“”) due to a kernel bug, hence it’s not reliable (see issue 595).
Changed in version 3.1.0: no longer hangs on Windows.
Changed in version 4.1.0: new position, mode and flags fields on Linux.
- net_connections(kind='inet')
Return socket connections opened by process as a list of named tuples. To get system-wide connections use
psutil.net_connections()
. Every named tuple provides 6 attributes:fd: the socket file descriptor. If the connection refers to the current process this may be passed to socket.fromfd to obtain a usable socket object. On Windows, FreeBSD and SunOS this is always set to
-1
.family: the address family, either AF_INET, AF_INET6 or AF_UNIX.
type: the address type, either SOCK_STREAM, SOCK_DGRAM or SOCK_SEQPACKET. .
laddr: the local address as a
(ip, port)
named tuple or apath
in case of AF_UNIX sockets. For UNIX sockets see notes below.raddr: the remote address as a
(ip, port)
named tuple or an absolutepath
in case of UNIX sockets. When the remote endpoint is not connected you’ll get an empty tuple (AF_INET*) or""
(AF_UNIX). For UNIX sockets see notes below.status: represents the status of a TCP connection. The return value is one of the
psutil.CONN_*
constants. For UDP and UNIX sockets this is always going to bepsutil.CONN_NONE
.
The kind parameter is a string which filters for connections that fit the following criteria:
Kind value
Connections using
"inet"
IPv4 and IPv6
"inet4"
IPv4
"inet6"
IPv6
"tcp"
TCP
"tcp4"
TCP over IPv4
"tcp6"
TCP over IPv6
"udp"
UDP
"udp4"
UDP over IPv4
"udp6"
UDP over IPv6
"unix"
UNIX socket (both UDP and TCP protocols)
"all"
the sum of all the possible families and protocols
Example:
>>> import psutil >>> p = psutil.Process(1694) >>> p.name() 'firefox' >>> p.net_connections() [pconn(fd=115, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=addr(ip='10.0.0.1', port=48776), raddr=addr(ip='93.186.135.91', port=80), status='ESTABLISHED'), pconn(fd=117, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=addr(ip='10.0.0.1', port=43761), raddr=addr(ip='72.14.234.100', port=80), status='CLOSING'), pconn(fd=119, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=addr(ip='10.0.0.1', port=60759), raddr=addr(ip='72.14.234.104', port=80), status='ESTABLISHED'), pconn(fd=123, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=addr(ip='10.0.0.1', port=51314), raddr=addr(ip='72.14.234.83', port=443), status='SYN_SENT')]
Note
(Solaris) UNIX sockets are not supported.
Note
(Linux, FreeBSD) raddr field for UNIX sockets is always set to “”. This is a limitation of the OS.
Note
(OpenBSD) laddr and raddr fields for UNIX sockets are always set to “”. This is a limitation of the OS.
Note
(AIX)
psutil.AccessDenied
is always raised unless running as root (lsof does the same).Changed in version 5.3.0: : laddr and raddr are named tuples.
Changed in version 6.0.0: : method renamed from connections to net_connections.
- connections()
Same as
net_connections()
(deprecated).Warning
deprecated in version 6.0.0; use
net_connections()
instead.
- is_running()
Return whether the current process is running in the current process list. This is reliable also in case the process is gone and its PID reused by another process, therefore it must be preferred over doing
psutil.pid_exists(p.pid)
. If PID has been reused this method will also remove the process fromprocess_iter()
internal cache.Note
this will return
True
also if the process is a zombie (p.status() == psutil.STATUS_ZOMBIE
).Changed in version 6.0.0: : automatically remove process from
process_iter()
internal cache if PID has been reused by another process.
- send_signal(signal)
Send a signal to process (see signal module constants) preemptively checking whether PID has been reused. On UNIX this is the same as
os.kill(pid, sig)
. On Windows only SIGTERM, CTRL_C_EVENT and CTRL_BREAK_EVENT signals are supported and SIGTERM is treated as an alias forkill()
. See also how to kill a process tree and terminate my children.Changed in version 3.2.0: support for CTRL_C_EVENT and CTRL_BREAK_EVENT signals on Windows was added.
- suspend()
Suspend process execution with SIGSTOP signal preemptively checking whether PID has been reused. On UNIX this is the same as
os.kill(pid, signal.SIGSTOP)
. On Windows this is done by suspending all process threads execution.
- resume()
Resume process execution with SIGCONT signal preemptively checking whether PID has been reused. On UNIX this is the same as
os.kill(pid, signal.SIGCONT)
. On Windows this is done by resuming all process threads execution.
- terminate()
Terminate the process with SIGTERM signal preemptively checking whether PID has been reused. On UNIX this is the same as
os.kill(pid, signal.SIGTERM)
. On Windows this is an alias forkill()
. See also how to kill a process tree and terminate my children.
- kill()
Kill the current process by using SIGKILL signal preemptively checking whether PID has been reused. On UNIX this is the same as
os.kill(pid, signal.SIGKILL)
. On Windows this is done by using TerminateProcess. See also how to kill a process tree and terminate my children.
- wait(timeout=None)
Wait for a process PID to terminate. The details about the return value differ on UNIX and Windows.
On UNIX: if the process terminated normally, the return value is a positive integer >= 0 indicating the exit code. If the process was terminated by a signal return the negated value of the signal which caused the termination (e.g.
-SIGTERM
). If PID is not a children of os.getpid (current process) just wait until the process disappears and returnNone
. If PID does not exist returnNone
immediately.On Windows: always return the exit code, which is a positive integer as returned by GetExitCodeProcess.
timeout is expressed in seconds. If specified and the process is still alive raise
TimeoutExpired
exception.timeout=0
can be used in non-blocking apps: it will either return immediately or raiseTimeoutExpired
.The return value is cached. To wait for multiple processes use
psutil.wait_procs()
.>>> import psutil >>> p = psutil.Process(9891) >>> p.terminate() >>> p.wait() <Negsignal.SIGTERM: -15>
Changed in version 5.7.1: return value is cached (instead of returning
None
).Changed in version 5.7.1: on POSIX, in case of negative signal, return it as a human readable enum.
- class psutil.Popen(*args, **kwargs)
Same as subprocess.Popen but in addition it provides all
psutil.Process
methods in a single class. For the following methods which are common to both classes, psutil implementation takes precedence:send_signal()
,terminate()
,kill()
. This is done in order to avoid killing another process in case its PID has been reused, fixing BPO-6973.>>> import psutil >>> from subprocess import PIPE >>> >>> p = psutil.Popen(["/usr/bin/python", "-c", "print('hello')"], stdout=PIPE) >>> p.name() 'python' >>> p.username() 'giampaolo' >>> p.communicate() ('hello\n', None) >>> p.wait(timeout=2) 0 >>>
Changed in version 4.4.0: added context manager support
Windows services
- psutil.win_service_iter()
Return an iterator yielding a
WindowsService
class instance for all Windows services installed.Added in version 4.2.0.
Availability: Windows
- psutil.win_service_get(name)
Get a Windows service by name, returning a
WindowsService
instance. Raisepsutil.NoSuchProcess
if no service with such name exists.Added in version 4.2.0.
Availability: Windows
- class psutil.WindowsService
Represents a Windows service with the given name. This class is returned by
win_service_iter()
andwin_service_get()
functions and it is not supposed to be instantiated directly.- name()
The service name. This string is how a service is referenced and can be passed to
win_service_get()
to get a newWindowsService
instance.
- display_name()
The service display name. The value is cached when this class is instantiated.
- binpath()
The fully qualified path to the service binary/exe file as a string, including command line arguments.
- username()
The name of the user that owns this service.
- start_type()
A string which can either be “automatic”, “manual” or “disabled”.
- pid()
The process PID, if any, else None. This can be passed to
Process
class to control the service’s process.
- status()
Service status as a string, which may be either “running”, “paused”, “start_pending”, “pause_pending”, “continue_pending”, “stop_pending” or “stopped”.
- description()
Service long description.
- as_dict()
Utility method retrieving all the information above as a dictionary.
Added in version 4.2.0.
Availability: Windows
Example code:
>>> import psutil
>>> list(psutil.win_service_iter())
[<WindowsService(name='AeLookupSvc', display_name='Application Experience') at 38850096>,
<WindowsService(name='ALG', display_name='Application Layer Gateway Service') at 38850128>,
<WindowsService(name='APNMCP', display_name='Ask Update Service') at 38850160>,
<WindowsService(name='AppIDSvc', display_name='Application Identity') at 38850192>,
...]
>>> s = psutil.win_service_get('alg')
>>> s.as_dict()
{'binpath': 'C:\\Windows\\System32\\alg.exe',
'description': 'Provides support for 3rd party protocol plug-ins for Internet Connection Sharing',
'display_name': 'Application Layer Gateway Service',
'name': 'alg',
'pid': None,
'start_type': 'manual',
'status': 'stopped',
'username': 'NT AUTHORITY\\LocalService'}
Constants
Operating system constants
- psutil.POSIX
- psutil.LINUX
- psutil.WINDOWS
- psutil.MACOS
- psutil.FREEBSD
- psutil.NETBSD
- psutil.OPENBSD
- psutil.BSD
- psutil.SUNOS
- psutil.AIX
bool
constants which define what platform you’re on. E.g. if on Windows,WINDOWS
constant will beTrue
, all others will beFalse
.Added in version 4.0.0.
Changed in version 5.4.0: added AIX
- psutil.PROCFS_PATH
The path of the /proc filesystem on Linux, Solaris and AIX (defaults to
"/proc"
). You may want to re-set this constant right after importing psutil in case your /proc filesystem is mounted elsewhere or if you want to retrieve information about Linux containers such as Docker, Heroku or LXC (see here for more info). It must be noted that this trick works only for APIs which rely on /proc filesystem (e.g. memory APIs and mostProcess
class methods).Availability: Linux, Solaris, AIX
Added in version 3.2.3.
Changed in version 3.4.2: also available on Solaris.
Changed in version 5.4.0: also available on AIX.
Process status constants
- psutil.STATUS_RUNNING
- psutil.STATUS_SLEEPING
- psutil.STATUS_DISK_SLEEP
- psutil.STATUS_STOPPED
- psutil.STATUS_TRACING_STOP
- psutil.STATUS_ZOMBIE
- psutil.STATUS_DEAD
- psutil.STATUS_WAKE_KILL
- psutil.STATUS_WAKING
- psutil.STATUS_PARKED(Linux)
- psutil.STATUS_IDLE(Linux, macOS, FreeBSD)
- psutil.STATUS_LOCKED(FreeBSD)
- psutil.STATUS_WAITING(FreeBSD)
- psutil.STATUS_SUSPENDED(NetBSD)
Represent a process status. Returned by
psutil.Process.status()
.Added in version 3.4.1:
STATUS_SUSPENDED
(NetBSD)Added in version 5.4.7:
STATUS_PARKED
(Linux)
Process priority constants
- psutil.REALTIME_PRIORITY_CLASS
- psutil.HIGH_PRIORITY_CLASS
- psutil.ABOVE_NORMAL_PRIORITY_CLASS
- psutil.NORMAL_PRIORITY_CLASS
- psutil.IDLE_PRIORITY_CLASS
- psutil.BELOW_NORMAL_PRIORITY_CLASS
Represent the priority of a process on Windows (see SetPriorityClass). They can be used in conjunction with
psutil.Process.nice()
to get or set process priority.Availability: Windows
- psutil.IOPRIO_CLASS_NONE
- psutil.IOPRIO_CLASS_RT
- psutil.IOPRIO_CLASS_BE
- psutil.IOPRIO_CLASS_IDLE
A set of integers representing the I/O priority of a process on Linux. They can be used in conjunction with
psutil.Process.ionice()
to get or set process I/O priority. IOPRIO_CLASS_NONE and IOPRIO_CLASS_BE (best effort) is the default for any process that hasn’t set a specific I/O priority. IOPRIO_CLASS_RT (real time) means the process is given first access to the disk, regardless of what else is going on in the system. IOPRIO_CLASS_IDLE means the process will get I/O time when no-one else needs the disk. For further information refer to manuals of ionice command line utility or ioprio_get system call.Availability: Linux
- psutil.IOPRIO_VERYLOW
- psutil.IOPRIO_LOW
- psutil.IOPRIO_NORMAL
- psutil.IOPRIO_HIGH
A set of integers representing the I/O priority of a process on Windows. They can be used in conjunction with
psutil.Process.ionice()
to get or set process I/O priority.Availability: Windows
Added in version 5.6.2.
Process resources constants
Linux / FreeBSD:
Linux specific:
FreeBSD specific:
Constants used for getting and setting process resource limits to be used in
conjunction with psutil.Process.rlimit()
. See resource.getrlimit
for further information.
Availability: Linux, FreeBSD
Changed in version 5.7.3: added FreeBSD support, added RLIMIT_SWAP
,
RLIMIT_SBSIZE
, RLIMIT_NPTS
.
Connections constants
- psutil.CONN_ESTABLISHED
- psutil.CONN_SYN_SENT
- psutil.CONN_SYN_RECV
- psutil.CONN_FIN_WAIT1
- psutil.CONN_FIN_WAIT2
- psutil.CONN_TIME_WAIT
- psutil.CONN_CLOSE
- psutil.CONN_CLOSE_WAIT
- psutil.CONN_LAST_ACK
- psutil.CONN_LISTEN
- psutil.CONN_CLOSING
- psutil.CONN_NONE
- psutil.CONN_DELETE_TCB(Windows)
- psutil.CONN_IDLE(Solaris)
- psutil.CONN_BOUND(Solaris)
A set of strings representing the status of a TCP connection. Returned by
psutil.Process.net_connections()
andpsutil.net_connections()
(status field).
Hardware constants
- psutil.AF_LINK
Constant which identifies a MAC address associated with a network interface. To be used in conjunction with
psutil.net_if_addrs()
.Added in version 3.0.0.
- psutil.NIC_DUPLEX_FULL
- psutil.NIC_DUPLEX_HALF
- psutil.NIC_DUPLEX_UNKNOWN
Constants which identifies whether a NIC (network interface card) has full or half mode speed. NIC_DUPLEX_FULL means the NIC is able to send and receive data (files) simultaneously, NIC_DUPLEX_FULL means the NIC can either send or receive data at a time. To be used in conjunction with
psutil.net_if_stats()
.Added in version 3.0.0.
- psutil.POWER_TIME_UNKNOWN
- psutil.POWER_TIME_UNLIMITED
Whether the remaining time of the battery cannot be determined or is unlimited. May be assigned to
psutil.sensors_battery()
’s secsleft field.Added in version 5.1.0.
- psutil.version_info
A tuple to check psutil installed version. Example:
>>> import psutil >>> if psutil.version_info >= (4, 5): ... pass
Recipes
Find process by name
Check string against Process.name()
:
import psutil
def find_procs_by_name(name):
"Return a list of processes matching 'name'."
ls = []
for p in psutil.process_iter(['name']):
if p.info['name'] == name:
ls.append(p)
return ls
A bit more advanced, check string against Process.name()
,
Process.exe()
and Process.cmdline()
:
import os
import psutil
def find_procs_by_name(name):
"Return a list of processes matching 'name'."
ls = []
for p in psutil.process_iter(["name", "exe", "cmdline"]):
if name == p.info['name'] or \
p.info['exe'] and os.path.basename(p.info['exe']) == name or \
p.info['cmdline'] and p.info['cmdline'][0] == name:
ls.append(p)
return ls
Kill process tree
import os
import signal
import psutil
def kill_proc_tree(pid, sig=signal.SIGTERM, include_parent=True,
timeout=None, on_terminate=None):
"""Kill a process tree (including grandchildren) with signal
"sig" and return a (gone, still_alive) tuple.
"on_terminate", if specified, is a callback function which is
called as soon as a child terminates.
"""
assert pid != os.getpid(), "won't kill myself"
parent = psutil.Process(pid)
children = parent.children(recursive=True)
if include_parent:
children.append(parent)
for p in children:
try:
p.send_signal(sig)
except psutil.NoSuchProcess:
pass
gone, alive = psutil.wait_procs(children, timeout=timeout,
callback=on_terminate)
return (gone, alive)
Filtering and sorting processes
A collection of code samples showing how to use process_iter()
to filter processes and sort them. Setup:
>>> import psutil
>>> from pprint import pprint as pp
Processes owned by user:
>>> import getpass
>>> pp([(p.pid, p.info['name']) for p in psutil.process_iter(['name', 'username']) if p.info['username'] == getpass.getuser()])
(16832, 'bash'),
(19772, 'ssh'),
(20492, 'python')]
Processes actively running:
>>> pp([(p.pid, p.info) for p in psutil.process_iter(['name', 'status']) if p.info['status'] == psutil.STATUS_RUNNING])
[(1150, {'name': 'Xorg', 'status': 'running'}),
(1776, {'name': 'unity-panel-service', 'status': 'running'}),
(20492, {'name': 'python', 'status': 'running'})]
Processes using log files:
>>> for p in psutil.process_iter(['name', 'open_files']):
... for file in p.info['open_files'] or []:
... if file.path.endswith('.log'):
... print("%-5s %-10s %s" % (p.pid, p.info['name'][:10], file.path))
...
1510 upstart /home/giampaolo/.cache/upstart/unity-settings-daemon.log
2174 nautilus /home/giampaolo/.local/share/gvfs-metadata/home-ce08efac.log
2650 chrome /home/giampaolo/.config/google-chrome/Default/data_reduction_proxy_leveldb/000003.log
Processes consuming more than 500M of memory:
>>> pp([(p.pid, p.info['name'], p.info['memory_info'].rss) for p in psutil.process_iter(['name', 'memory_info']) if p.info['memory_info'].rss > 500 * 1024 * 1024])
[(2650, 'chrome', 532324352),
(3038, 'chrome', 1120088064),
(21915, 'sublime_text', 615407616)]
Top 3 processes which consumed the most CPU time:
>>> pp([(p.pid, p.info['name'], sum(p.info['cpu_times'])) for p in sorted(psutil.process_iter(['name', 'cpu_times']), key=lambda p: sum(p.info['cpu_times'][:2]))][-3:])
[(2721, 'chrome', 10219.73),
(1150, 'Xorg', 11116.989999999998),
(2650, 'chrome', 18451.97)]
Bytes conversion
import psutil
def bytes2human(n):
# http://code.activestate.com/recipes/578019
# >>> bytes2human(10000)
# '9.8K'
# >>> bytes2human(100001221)
# '95.4M'
symbols = ('K', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y')
prefix = {}
for i, s in enumerate(symbols):
prefix[s] = 1 << (i + 1) * 10
for s in reversed(symbols):
if abs(n) >= prefix[s]:
value = float(n) / prefix[s]
return '%.1f%s' % (value, s)
return "%sB" % n
total = psutil.disk_usage('/').total
print(total)
print(bytes2human(total))
…prints:
100399730688
93.5G
FAQs
Q: Why do I get
AccessDenied
for certain processes?A: This may happen when you query processes owned by another user, especially on macOS (see issue #883) and Windows. Unfortunately there’s not much you can do about this except running the Python process with higher privileges. On Unix you may run the Python process as root or use the SUID bit (
ps
andnetstat
does this). On Windows you may run the Python process as NT AUTHORITY\SYSTEM or install the Python script as a Windows service (ProcessHacker does this).Q: is MinGW supported on Windows?
A: no, you should Visual Studio (see development guide).
Running tests
$ python3 -m psutil.tests
Debug mode
If you want to debug unusual situations or want to report a bug, it may be
useful to enable debug mode via PSUTIL_DEBUG
environment variable.
In this mode, psutil may (or may not) print additional information to stderr.
Usually these are error conditions which are not severe, and hence are ignored
(instead of crashing).
Unit tests automatically run with debug mode enabled.
On UNIX:
$ PSUTIL_DEBUG=1 python3 script.py
psutil-debug [psutil/_psutil_linux.c:150]> setmntent() failed (ignored)
On Windows:
set PSUTIL_DEBUG=1 python.exe script.py
psutil-debug [psutil/arch/windows/proc.c:90]> NtWow64ReadVirtualMemory64(pbi64.PebBaseAddress) -> 998 (Unknown error) (ignored)
Security
To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.
Development guide
If you want to develop psutil take a look at the DEVGUIDE.rst.
Platforms support history
psutil 5.9.6 (2023-10): drop Python 3.4 and 3.5
psutil 5.9.1 (2022-05): drop Python 2.6
psutil 5.9.0 (2021-12): add MidnightBSD
psutil 5.8.0 (2020-12): add PyPy 2 on Windows
psutil 5.7.1 (2020-07): add Windows Nano
psutil 5.7.0 (2020-02): drop Windows XP & Windows Server 2003
psutil 5.7.0 (2020-02): add PyPy 3 on Windows
psutil 5.4.0 (2017-11): add AIX
psutil 3.4.1 (2016-01): add NetBSD
psutil 3.3.0 (2015-11): add OpenBSD
psutil 1.0.0 (2013-07): add Solaris
psutil 0.1.1 (2009-03): add FreeBSD
psutil 0.1.0 (2009-01): add Linux, Windows, macOS
Supported Python versions at the time of writing are cPython 2.7, 3.6+ and PyPy3.
Timeline
2024-10-17: 6.1.0 - what’s new - diff
2024-06-18: 6.0.0 - what’s new - diff
2024-01-19: 5.9.8 - what’s new - diff
2023-12-17: 5.9.7 - what’s new - diff
2023-10-15: 5.9.6 - what’s new - diff
2023-04-17: 5.9.5 - what’s new - diff
2022-11-07: 5.9.4 - what’s new - diff
2022-10-18: 5.9.3 - what’s new - diff
2022-09-04: 5.9.2 - what’s new - diff
2022-05-20: 5.9.1 - what’s new - diff
2021-12-29: 5.9.0 - what’s new - diff
2020-12-19: 5.8.0 - what’s new - diff
2020-10-24: 5.7.3 - what’s new - diff
2020-07-15: 5.7.2 - what’s new - diff
2020-07-15: 5.7.1 - what’s new - diff
2020-02-18: 5.7.0 - what’s new - diff
2019-11-26: 5.6.7 - what’s new - diff
2019-11-25: 5.6.6 - what’s new - diff
2019-11-06: 5.6.5 - what’s new - diff
2019-11-04: 5.6.4 - what’s new - diff
2019-06-11: 5.6.3 - what’s new - diff
2019-04-26: 5.6.2 - what’s new - diff
2019-03-11: 5.6.1 - what’s new - diff
2019-03-05: 5.6.0 - what’s new - diff
2019-02-15: 5.5.1 - what’s new - diff
2019-01-23: 5.5.0 - what’s new - diff
2018-10-30: 5.4.8 - what’s new - diff
2018-08-14: 5.4.7 - what’s new - diff
2018-06-07: 5.4.6 - what’s new - diff
2018-04-13: 5.4.5 - what’s new - diff
2018-04-13: 5.4.4 - what’s new - diff
2018-01-01: 5.4.3 - what’s new - diff
2017-12-07: 5.4.2 - what’s new - diff
2017-11-08: 5.4.1 - what’s new - diff
2017-10-12: 5.4.0 - what’s new - diff
2017-09-10: 5.3.1 - what’s new - diff
2017-09-01: 5.3.0 - what’s new - diff
2017-04-10: 5.2.2 - what’s new - diff
2017-03-24: 5.2.1 - what’s new - diff
2017-03-05: 5.2.0 - what’s new - diff
2017-02-07: 5.1.3 - what’s new - diff
2017-02-03: 5.1.2 - what’s new - diff
2017-02-03: 5.1.1 - what’s new - diff
2017-02-01: 5.1.0 - what’s new - diff
2016-12-21: 5.0.1 - what’s new - diff
2016-11-06: 5.0.0 - what’s new - diff
2016-10-05: 4.4.2 - what’s new - diff
2016-10-25: 4.4.1 - what’s new - diff
2016-10-23: 4.4.0 - what’s new - diff
2016-09-01: 4.3.1 - what’s new - diff
2016-06-18: 4.3.0 - what’s new - diff
2016-05-14: 4.2.0 - what’s new - diff
2016-03-12: 4.1.0 - what’s new - diff
2016-02-17: 4.0.0 - what’s new - diff
2016-01-20: 3.4.2 - what’s new - diff
2016-01-15: 3.4.1 - what’s new - diff
2015-11-25: 3.3.0 - what’s new - diff
2015-10-04: 3.2.2 - what’s new - diff
2015-09-03: 3.2.1 - what’s new - diff
2015-09-02: 3.2.0 - what’s new - diff
2015-07-15: 3.1.1 - what’s new - diff
2015-07-15: 3.1.0 - what’s new - diff
2015-06-18: 3.0.1 - what’s new - diff
2015-06-13: 3.0.0 - what’s new - diff
2015-02-02: 2.2.1 - what’s new - diff
2015-01-06: 2.2.0 - what’s new - diff
2014-09-26: 2.1.3 - what’s new - diff
2014-09-21: 2.1.2 - what’s new - diff
2014-04-30: 2.1.1 - what’s new - diff
2014-04-08: 2.1.0 - what’s new - diff
2014-03-10: 2.0.0 - what’s new - diff
2013-11-25: 1.2.1 - what’s new - diff
2013-11-20: 1.2.0 - what’s new - diff
2013-10-22: 1.1.2 - what’s new - diff
2013-10-08: 1.1.1 - what’s new - diff
2013-09-28: 1.1.0 - what’s new - diff
2013-07-12: 1.0.1 - what’s new - diff
2013-07-10: 1.0.0 - what’s new - diff
2013-05-03: 0.7.1 - what’s new - diff
2013-04-12: 0.7.0 - what’s new - diff
2012-08-16: 0.6.1 - what’s new - diff
2012-08-13: 0.6.0 - what’s new - diff
2012-06-29: 0.5.1 - what’s new - diff
2012-06-27: 0.5.0 - what’s new - diff
2011-12-14: 0.4.1 - what’s new - diff
2011-10-29: 0.4.0 - what’s new - diff
2011-07-08: 0.3.0 - what’s new - diff
2011-03-20: 0.2.1 - what’s new - diff
2010-11-13: 0.2.0 - what’s new - diff
2010-03-02: 0.1.3 - what’s new - diff
2009-05-06: 0.1.2 - what’s new - diff
2009-03-06: 0.1.1 - what’s new - diff
2009-01-27: 0.1.0 - what’s new - diff