psutil documentation

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) in Python. It is useful mainly for system monitoring, profiling and limiting process resources and management of running processes. It implements many functionalities offered by command line tools such as: ps, top, lsof, netstat, ifconfig, who, df, kill, free, nice, ionice, iostat, iotop, uptime, pidof, tty, taskset, pmap. It currently supports Linux, Windows, OSX, Sun Solaris, FreeBSD, OpenBSD and NetBSD, both 32-bit and 64-bit architectures, with Python versions from 2.6 to 3.5 (users of Python 2.4 and 2.5 may use 2.1.3 version). PyPy is also known to work.

The psutil documentation you’re reading is distributed as a single HTML page.

Processes

Functions

psutil.pids()

Return a list of current running PIDs. To iterate over all processes process_iter() should be preferred.

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.process_iter()

Return an iterator yielding a Process class instance for all running processes on the local machine. Every instance is only created once and then cached into an internal table which is updated every time an element is yielded. Cached Process instances are checked for identity so that you’re safe in case a PID has been reused by another process, in which case the cached instance is updated. This is should be preferred over psutil.pids() for iterating over processes. Sorting order in which processes are returned is based on their PID. Example usage:

import psutil

for proc in psutil.process_iter():
    try:
        pinfo = proc.as_dict(attrs=['pid', 'name'])
    except psutil.NoSuchProcess:
        pass
    else:
        print(pinfo)
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 (it may be None). callback is a function which gets called every time a process terminates (a Process instance is passed as callback argument). Function will return as soon as all processes terminate or when timeout occurs. Tipical use case is:

  • send SIGTERM to a list of processes
  • give them some time to terminate
  • send SIGKILL to those ones which are still alive

Example:

import psutil

def on_terminate(proc):
    print("process {} terminated with exit code {}".format(proc, proc.returncode))

procs = [...]  # a list of Process instances
for p in procs:
    p.terminate()
gone, alive = 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 if Process.name() was previosly 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). Depending on the method called the OS may be able to succeed in retrieving the process information or not. Note: this is a subclass of NoSuchProcess so if you’re not interested in retrieving zombies (e.g. when using process_iter()) you can ignore this exception and just catch NoSuchProcess.

New 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. “name” is the name of the process (may be None).

class psutil.TimeoutExpired(seconds, pid=None, name=None, msg=None)

Raised by Process.wait() if timeout expires and process is still alive.

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. When accessing methods of this class always be prepared to catch NoSuchProcess, ZombieProcess and AccessDenied 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 and creation time). As such it can also be used with set()s.

Warning

the way this class is bound to a process is via its PID. That means that if the Process instance is old enough and the PID has been reused in the meantime you might end up interacting with another process. The only exceptions for which process identity is preemptively checked (via PID + creation time) and guaranteed are for nice() (set), ionice() (set), cpu_affinity() (set), rlimit() (set), children(), parent(), suspend() resume(), send_signal(), terminate(), and kill() methods. To prevent this problem for all other methods you can use is_running() before querying the process or use process_iter() in case you’re iterating over all processes.

pid

The process PID.

ppid()

The process parent pid. On Windows the return value is cached after first call.

name()

The process name.

exe()

The process executable as an absolute path. On some systems this may also be an empty string. The return value is cached after first call.

cmdline()

The command line this process has been called with.

environ()

The environment variables of the process as a dict. Note: this might not reflect changes made after the process started.

Availability: Linux, OSX, Windows

New in version 4.0.0.

create_time()

The process creation time as a floating point number expressed in seconds since the epoch, in UTC. 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 (e.g. ['cpu_times', 'name']), else all public (read only) attributes are assumed. ad_value is the value which gets assigned to a dict key in case AccessDenied or ZombieProcess exception is raised when retrieving that particular process information.

>>> import psutil
>>> p = psutil.Process()
>>> p.as_dict(attrs=['pid', 'name', 'username'])
{'username': 'giampaolo', 'pid': 12366, 'name': 'python'}

Changed in version 3.0.0: ad_value is used also when incurring into ZombieProcess exception, not only AccessDenied

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 return None.

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.

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 namedtuple. 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 namedtuple. 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 to 20. 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() (UNIX only). 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). On Linux ioclass is one of the psutil.IOPRIO_CLASS_* constants. value is a number which goes from 0 to 7. The higher the value, the lower the I/O priority of the process. On Windows only ioclass is used and it can be set to 2 (normal), 1 (low) or 0 (very low). The example below sets IDLE priority class for the current process, meaning it will only get I/O time when no other process needs the disk:

>>> import psutil
>>> p = psutil.Process()
>>> p.ionice(psutil.IOPRIO_CLASS_IDLE)  # set
>>> p.ionice()  # get
pionice(ioclass=<IOPriority.IOPRIO_CLASS_IDLE: 3>, value=0)
>>>

On Windows only ioclass is used and it can be set to 2 (normal), 1 (low) or 0 (very low).

Availability: Linux and Windows > Vista

Changed in version 3.0.0: on >= Python 3.4 the returned ioclass constant is an enum instead of a plain integer.

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(). Example:

>>> import psutil
>>> p = psutil.Process()
>>> # process may open no more than 128 file descriptors
>>> p.rlimit(psutil.RLIMIT_NOFILE, (128, 128))
>>> # process may create files no bigger than 1024 bytes
>>> p.rlimit(psutil.RLIMIT_FSIZE, (1024, 1024))
>>> # get
>>> p.rlimit(psutil.RLIMIT_FSIZE)
(1024, 1024)
>>>

Availability: Linux

io_counters()

Return process I/O statistics as a namedtuple including the number of read and write operations performed by the process and the amount of bytes read and written. For Linux refer to /proc filesysem documentation. On BSD there’s apparently no way to retrieve bytes counters, hence -1 is returned for read_bytes and write_bytes fields. OSX is not supported.

>>> import psutil
>>> p = psutil.Process()
>>> p.io_counters()
pio(read_count=454556, write_count=3456, read_bytes=110592, write_bytes=0)

Availability: all platforms except OSX and Solaris

num_ctx_switches()

The number voluntary and involuntary context switches performed by this process.

num_fds()

The number of file descriptors used by this process.

Availability: UNIX

num_handles()

The number of handles used by this process.

Availability: Windows

num_threads()

The number of threads used by this process.

threads()

Return threads opened by process as a list of namedtuples including thread id and thread CPU times (user/system). On OpenBSD this method requires root access.

cpu_times()

Return a (user, system, children_user, children_system) namedtuple representing the accumulated process time, in seconds (see explanation). On Windows and OSX only user and system are filled, the others are set to 0. This is similar to os.times() but can be used for any process PID.

Changed in version 4.1.0: return two extra fields: children_user and children_system.

cpu_percent(interval=None)

Return a float representing the process CPU utilization as a percentage. The returned value refers to the utilization of a single CPU, i.e. it is not evenly split between the number of available CPU cores. When interval is > 0.0 compares process times to system CPU times elapsed before and after the interval (blocking). When interval is 0.0 or None 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 meaningless 0.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 least 0.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

a percentage > 100 is legitimate as it can result from a process with multiple threads running on different CPU cores.

Note

the returned value is explcitly not split evenly between all CPUs cores (differently from psutil.cpu_percent()). This means that a busy loop process running on a system with 2 CPU cores will be reported as having 100% CPU utilization instead of 50%. This was done in order to be consistent with UNIX’s “top” utility and also to make it easier to identify processes hogging CPU resources (independently from the number of CPU cores). It must be noted that in the example above taskmgr.exe on Windows will report 50% usage instead. To emulate Windows’s taskmgr.exe behavior you can do: p.cpu_percent() / psutil.cpu_count().

Warning

the first time this method is called with interval = 0.0 or None it will return a meaningless 0.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 certain process on a limited set of CPUs only. The number of eligible CPUs can be obtained with list(range(psutil.cpu_count())). ValueError will be raise on set in case an invalid CPU number is specified.

>>> import psutil
>>> psutil.cpu_count()
4
>>> p = psutil.Process()
>>> p.cpu_affinity()  # get
[0, 1, 2, 3]
>>> p.cpu_affinity([0])  # set; from now on, process will run on CPU #0 only
>>> p.cpu_affinity()
[0]
>>>
>>> # reset affinity against all CPUs
>>> all_cpus = list(range(psutil.cpu_count()))
>>> p.cpu_affinity(all_cpus)
>>>

Availability: Linux, Windows, FreeBSD

Changed in version 2.2.0: added support for FreeBSD

memory_info()

Return a namedtuple with variable fields depending on the platform representing memory information about the process. The “portable” fields available on all plaforms are rss and vms. All numbers are expressed in bytes.

Linux OSX BSD Solaris Windows
rss rss rss rss rss (alias for wset)
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 (see doc). 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 (see doc). 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 (see doc).
  • text (Linux, BSD): aka TRS (text resident set) the amount of memory devoted to executable code. This matches “top“‘s CODE column (see doc).
  • 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 (see doc).
  • lib (Linux): the memory used by shared libraries.
  • dirty (Linux): the number of dirty pages.

For 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: mutiple 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, OSX, 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 here. It does so by passing through the whole process address. As such it usually requires higher user privileges than memory_info() and is considerably slower. On platforms where extra fields are not implented this simply returns the same metrics as memory_info().

  • uss (Linux, OSX, 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 scripts/procsmem.py for an example application.

New 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 namedtuple field names returned by memory_info() and memory_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 namedtuples 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 is False each mapped region is shown as a single entity and the namedtuple will also include the mapped region’s address space (addr) and permission set (perms). See scripts/pmap.py for an example application.

Linux OSX Windows Solaris FreeBSD
rss rss rss rss rss
size private   anonymous private
pss swapped   locked ref_count
shared_clean dirtied     shadow_count
shared_dirty ref_count      
private_clean shadow_depth      
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),
 pmmap_grouped(path='/lib/x8664-linux-gnu/libcrypto.so.0.1', rss=34124, rss=32768, size=2134016, pss=15360, shared_clean=24576, shared_dirty=0, private_clean=0, private_dirty=8192, referenced=24576, anonymous=8192, swap=0),
 pmmap_grouped(path='[heap]',  rss=32768, size=139264, pss=32768, shared_clean=0, shared_dirty=0, private_clean=0, private_dirty=32768, referenced=32768, anonymous=32768, swap=0),
 pmmap_grouped(path='[stack]', rss=2465792, size=2494464, pss=2465792, shared_clean=0, shared_dirty=0, private_clean=0, private_dirty=2465792, referenced=2277376, anonymous=2465792, swap=0),
 ...]
>>>

Availability: All platforms except OpenBSD and NetBSD.

children(recursive=False)

Return the children of this process as a list of Process objects, preemptively checking whether PID has been reused. If recursive is True return all the parent descendants. 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.

open_files()

Return regular files opened by process as a list of namedtuples including the following fields:

  • path: the absolute file name.
  • fd: the file descriptor number; on Windows this is always -1.
  • position (Linux): the file (offset) position.
  • mode (Linux): a string indicating how the file was opened, similarly open‘s mode argument. Possible values are 'r', 'w', 'a', 'r+' and 'a+'. There’s no distinction between files opened in bynary 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/setup.py', fd=3, position=0, mode='r', flags=32768),
 popenfile(path='/var/log/monitd', fd=4, position=235542, mode='a', flags=33793)]

Warning

on Windows this is not fully reliable as due to some limitations of the Windows API the underlying implementation may hang when retrieving certain file handles. In order to work around that psutil on Windows Vista (and higher) spawns a thread and kills it if it’s not responding after 100ms. That implies that on Windows this method is not guaranteed to enumerate all regular file handles (see full discussion).

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.

connections(kind="inet")

Return socket connections opened by process as a list of namedtuples. To get system-wide connections use psutil.net_connections(). Every namedtuple provides 6 attributes:

  • fd: the socket file descriptor. This can be passed to socket.fromfd() to obtain a usable socket object. This is only available on UNIX; on Windows -1 is always returned.
  • family: the address family, either AF_INET, AF_INET6 or AF_UNIX.
  • type: the address type, either SOCK_STREAM or SOCK_DGRAM.
  • laddr: the local address as a (ip, port) tuple or a path in case of AF_UNIX sockets.
  • raddr: the remote address as a (ip, port) tuple or an absolute path in case of UNIX sockets. When the remote endpoint is not connected you’ll get an empty tuple (AF_INET) or None (AF_UNIX). On Linux AF_UNIX sockets will always have this set to None.
  • 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 be psutil.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.connections()
[pconn(fd=115, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=('10.0.0.1', 48776), raddr=('93.186.135.91', 80), status='ESTABLISHED'),
 pconn(fd=117, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=('10.0.0.1', 43761), raddr=('72.14.234.100', 80), status='CLOSING'),
 pconn(fd=119, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=('10.0.0.1', 60759), raddr=('72.14.234.104', 80), status='ESTABLISHED'),
 pconn(fd=123, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=('10.0.0.1', 51314), raddr=('72.14.234.83', 443), status='SYN_SENT')]
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).

Note

this will return True also if the process is a zombie (p.status() == psutil.STATUS_ZOMBIE).

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 for kill().

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 for kill().

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.

wait(timeout=None)

Wait for process termination and if the process is a children of the current one also return the exit code, else None. On Windows there’s no such limitation (exit code is always returned). If the process is already terminated immediately return None instead of raising NoSuchProcess. If timeout is specified and process is still alive raise TimeoutExpired exception. It can also be used in a non-blocking fashion by specifying timeout=0 in which case it will either return immediately or raise TimeoutExpired. To wait for multiple processes use psutil.wait_procs().

Popen class

class psutil.Popen(*args, **kwargs)

A more convenient interface to stdlib subprocess.Popen. It starts a sub process and deals with it exactly as when using subprocess.Popen but in addition it also provides all the methods of psutil.Process class in a single interface. For method names common to both classes such as send_signal(), terminate() and kill() psutil.Process implementation takes precedence. For a complete documentation refer to subprocess module documentation.

Note

Unlike subprocess.Popen this class preemptively checks wheter PID has been reused on send_signal(), terminate() and kill() so that you can’t accidentally terminate another process, fixing http://bugs.python.org/issue6973.

>>> 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
>>>

Windows services

psutil.win_service_iter()

Return an iterator yielding a WindowsService class instance for all Windows services installed.

New in version 4.2.0.

Availability: Windows

psutil.win_service_get(name)

Get a Windows service by name, returning a WindowsService instance. Raise psutil.NoSuchProcess if no service with such name exists.

New 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() and win_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 new WindowsService 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.

New in version 4.2.0.

Availability: Windows

Constants

psutil.POSIX
psutil.WINDOWS
psutil.LINUX
psutil.OSX
psutil.FREEBSD
psutil.NETBSD
psutil.OPENBSD
psutil.BSD
psutil.SUNOS

bool constants which define what platform you’re on. E.g. if on Windows, WINDOWS constant will be True, all others will be False.

New in version 4.0.0.

psutil.PROCFS_PATH

The path of the /proc filesystem on Linux and Solaris (defaults to “/proc”). You may want to re-set this constant right after importing psutil in case your /proc filesystem is mounted elsewhere.

Availability: Linux, Solaris

New in version 3.2.3.

Changed in version 3.4.2: also available on Solaris.

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_IDLE(OSX, FreeBSD)
psutil.STATUS_LOCKED(FreeBSD)
psutil.STATUS_WAITING(FreeBSD)
psutil.STATUS_SUSPENDED(NetBSD)

A set of strings representing the status of a process. Returned by psutil.Process.status().

New in version 3.4.1: STATUS_SUSPENDED (NetBSD)

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.connections() (status field).

psutil.ABOVE_NORMAL_PRIORITY_CLASS
psutil.BELOW_NORMAL_PRIORITY_CLASS
psutil.HIGH_PRIORITY_CLASS
psutil.IDLE_PRIORITY_CLASS
psutil.NORMAL_PRIORITY_CLASS
psutil.REALTIME_PRIORITY_CLASS

A set of integers representing the priority of a process on Windows (see MSDN documentation). They can be used in conjunction with psutil.Process.nice() to get or set process priority.

Availability: Windows

Changed in version 3.0.0: on Python >= 3.4 these constants are enums instead of a plain integer.

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

Changed in version 3.0.0: on Python >= 3.4 thse constants are enums instead of a plain integer.

psutil.RLIMIT_INFINITY
psutil.RLIMIT_AS
psutil.RLIMIT_CORE
psutil.RLIMIT_CPU
psutil.RLIMIT_DATA
psutil.RLIMIT_FSIZE
psutil.RLIMIT_LOCKS
psutil.RLIMIT_MEMLOCK
psutil.RLIMIT_MSGQUEUE
psutil.RLIMIT_NICE
psutil.RLIMIT_NOFILE
psutil.RLIMIT_NPROC
psutil.RLIMIT_RSS
psutil.RLIMIT_RTPRIO
psutil.RLIMIT_RTTIME
psutil.RLIMIT_RTPRIO
psutil.RLIMIT_SIGPENDING
psutil.RLIMIT_STACK

Constants used for getting and setting process resource limits to be used in conjunction with psutil.Process.rlimit(). See man prlimit for further information.

Availability: Linux

Constant which identifies a MAC address associated with a network interface. To be used in conjunction with psutil.net_if_addrs().

New 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().

New in version 3.0.0.

Development guide

If you plan on hacking on psutil (e.g. want to add a new feature or fix a bug) take a look at the development guide.