API Reference

Exceptions

psutil.NoSuchProcess?(pid, name=None, msg=None)

Raised when no process with the given PID is found in the current process list or when a process no longer exists (zombie).

Changed in 0.2.0: pid, name and msg arguments were added

psutil.AccessDenied?(pid=None, name=None, msg=None)

Raised when permission to perform an action is denied.

Changed in 0.2.0: pid, name and msg arguments were added

psutil.TimeoutExpired?(pid=None, name=None)

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

New in 0.2.1

Classes

psutil.Process(pid)

A class which represents an OS process.
  • pid
    The process pid.
  • ppid
    The process parent pid.
  • parent
    Return the parent process as a Process object. If no ppid is known then return None.
  • name
    The process name.
  • exe
    The process executable as an absolute path name.
New in 0.2.0
  • cmdline
    The command line process has been called with.
  • path
    The process path.
Deprecated in 0.2.0
  • create_time
    The process creation time as a floating point number expressed in seconds since the epoch, in UTC.
  • uids
    The real, effective and saved user ids of the current process as a nameduple. This is the same as os.getresuid() but per-process.
New in 0.2.1
Availability: UNIX
  • gids
    The real, effective and saved group ids of the current process as a nameduple. This is the same as os.getresgid() but per-process.
New in 0.2.1
Availability: UNIX
  • uid
    The real user id of the current process. This is the same as os.getuid() but per-process. On Windows always return -1.
Deprecated in 0.2.1: use uids property instead.
  • gid
    The real group id of the current process. This is the same as os.getgid() but per-process. On Windows always return -1.
Deprecated in 0.2.1: use gids property instead.
  • username
    The name of the user that owns the process. On UNIX this is calculated by using real process uid.
Changed in 2.0: Windows implementation has been rewritten in C for performace and pywin32 extension is no longer required.
  • status
    The current process status. The return value is one of the STATUS_* constants, which is an integer that can be used in conjunction with str() to obtain a human-readable form of the current process status. Example: 
    • >>> import psutil, os
>>> p = psutil.Process(os.getpid())
>>> p.status
0
>>> p.status == psutil.STATUS_RUNNING
True
>>> str(p.status)
'running'
>>>
New in 2.1
  • nice
    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. 
    • >>> p = psutil.Process(os.getpid())
>>> p.nice
0
>>> p.nice = 10  # set/change process priority
>>> p.nice
10
On Windows this is available as well by using GetPriorityClass and SetPriorityClass. psutil.*_PRIORITY_CLASS constants (explained here) can be used in conjunction. Example which increases process priority: 
>> p.nice = psutil.HIGH_PRIORITY_CLASS
New in 2.1
  • getcwd()
    Return a string representing the process current working directory.
Availability: Windows, Linux
  • get_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. 
    • >>> p.get_io_counters()
io(read_count=454556, write_count=3456, read_bytes=110592, write_bytes=0)
New in 2.1
Availability: Linux, Windows, FreeBSD
  • get_ionice()
    Return process I/O niceness (priority) as a namedtuple including priority class and priority data. See set_ionice below for more information.
New in 2.1
Availability: Linux
  • set_ionice(ioclass, iodata=None)
    Change process I/O niceness (priority). ioclass is one of the IOPRIO_CLASS_* constants. iodata is a number which goes from 0 to 7. The higher iodata value, the lower the I/O priority of the process. For further information refer to ionice command line utility or ioprio_set system call. 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, os
>>> p = psutil.Process(os.getpid())
>>> p.set_ionice(psutil.IOPRIO_CLASS_IDLE)
>>>
New in 2.1
Availability: Linux
  • get_num_threads()
    Return the number of threads used by this process.
New in 0.2.0
  • get_threads()
    Return threads opened by process as a list of namedtuples including thread id and thread CPU times (user/system).
New in 0.2.1
  • get_cpu_times()
    Return a tuple whose values are process CPU user and system times which means the amount of time expressed in seconds that a process has spent in user/system mode.
  • get_cpu_percent(interval=0.1)
    Return a float representing the process CPU utilization as a percentage. 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. In this case is recommended for accuracy that this function be called with at least 0.1 seconds between calls.
Changed in 0.2.0: interval parameter was added
  • get_memory_info()
    Return a tuple representing RSS (Resident Set Size) and VMS (Virtual Memory Size) in bytes.
    On UNIX RSS and VMS are the same values shown by ps. On Windows RSS and VMS refer to "Mem Usage" and "VM Size" columns of taskmgr.exe.
  • get_memory_percent()
    Compare physical system memory to process resident memory and calculate process memory utilization as a percentage.
  • get_children()
    Return the children of this process as a list of Process objects.
New in 0.2.0
  • get_open_files()
    Return files opened by process as a list of namedtuples including file absolute path name and file descriptor. On FreeBSD this is done by parsing lsof command output. If lsof is not installed on the system NotImplementedError exception is raised. Example: 
    • >>> import psutil, os
>>> f = open('file.ext', 'w')
>>> psutil.Process(os.getpid()).get_open_files()
[openfile(path='/home/giampaolo/svn/psutil/file.ext', fd=3)]
New in 0.2.0
Changed in 0.2.1: OSX implementation rewritten in C; no longer requiring lsof.
  • get_connections()
    Return all TCP and UPD connections opened by process as a list of namedtuples. 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 or AF_INET6
    • type: the address type, either SOCK_STREAM or SOCK_DGRAM
    • local_address: the local address as a (ip, port) tuple.
    • remote_address: the remote address as a (ip, port) tuple. When the remote endpoint is not connected the tuple is empty.
    • status: a string representing the TCP connections status. String values are supposed to match Linux's tcp_states.h header file across all platforms. For UDP sockets this is always going to be an empty string.
Example: 
>>> p = psutil.Process(1694)
>>> p.name
'firefox'
>>> p.get_connections()
[connection(fd=115, family=2, type=1, local_address=('10.0.0.1', 48776), remote_address=('93.186.135.91', 80), status='ESTABLISHED'),
 connection(fd=117, family=2, type=1, local_address=('10.0.0.1', 43761), remote_address=('72.14.234.100', 80), status='CLOSING'),
 connection(fd=119, family=2, type=1, local_address=('10.0.0.1', 60759), remote_address=('72.14.234.104', 80), status='ESTABLISHED'),
 connection(fd=123, family=2, type=1, local_address=('10.0.0.1', 51314), remote_address=('72.14.234.83', 443), status='SYN_SENT')]
On FreeBSD this is implemented by parsing lsof command output. If lsof is not installed on the system NotImplementedError exception is raised and for third party processes (different than os.getpid()) results can differ depending on user privileges.
New in 0.2.0
Changed in 0.2.1: OSX implementation rewritten in C; no longer requiring lsof.
  • is_running()
    Return whether the current process is running in the current process list.
  • send_signal(signal)
    Send a signal to process (see signal module constants). On Windows only SIGTERM is valid and is treated as an alias for kill().
New in 0.2.0
  • suspend()
    Suspend process execution with SIGSTOP signal. On Windows this is done by suspending all process threads execution.
  • resume()
    Resume process execution with SIGCONT signal. On Windows this is done by resuming all process threads execution.
  • terminate()
    Terminate the process with SIGTERM signal. On Windows this is an alias for kill().
New in 0.2.0
  • kill()
    Kill the current process by using SIGKILL signal.
Changed in 0.2.0: no longer accepts sig keyword argument - use send_signal() instead.
  • 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 does not raise NoSuchProcess exception but just return None immediately. If timeout is specified and process is still alive raises TimeoutExpired exception.
New in 0.2.1



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 class but in addition also provides all the properties and methods of psutil.Process class in a unique interface. For method names common to both classes such as kill() and terminate(), psutil.Process implementation takes precedence. For a complete documentation refers to subprocess module documentation.
New in 0.2.1

Functions

psutil.get_pid_list()

Return a list of current running PIDs.

psutil.pid_exists(pid)

Check whether the given PID exists in the current process list. This is faster than doing pid in psutil.get_pid_list() and should be preferred.

psutil.process_iter()

Return an iterator yielding a Process class instances for all running processes on the local machine. This should be preferred over doing for pid in psutil.get_pid_list(): psutil.Process(pid) as it safe from race conditions.

System related objects

psutil.cpu_percent(interval=0.1)

Return a float representing the current system-wide CPU utilization as a percentage. When interval is > 0.0 compares system CPU times elapsed before and after the interval (blocking). When interval is 0.0 or None compares system CPU times elapsed since last call or module import, returning immediately. In this case is recommended for accuracy that this function be called with at least 0.1 seconds between calls.

Changed in 0.2.0: interval parameter was added

psutil.cpu_times()

Return system CPU times as a namedtuple. Every CPU time is accessible in form of a CPUTimes attribute and represents the time CPU has spent in the given mode.
The attributes availability varies depending on the platform. Here follows a list of all available attributes:

- user
- system
- idle
- nice (UNIX)
- iowait (Linux)
- irq (Linux, FreeBSD)
- softirq (Linux)

psutil.avail_phymem()
psutil.used_phymem()

Return the amount of available and used physical memory on the system, in bytes. For total physical memory use psutil.BOOT_TIME constant.

psutil.total_virtmem()
psutil.avail_virtmem()
psutil.used_virtmem()

Return the amount of total, available and used virtual memory on the system, in bytes.
On Linux they match the values returned by free command line utility. On OS X and FreeBSD they represent the same values as returned by sysctl vm.vmtotal. On Windows they are determined by reading the *PageFile values of MEMORYSTATUSEX structure.

psutil.cached_phymem()

Return the amount of cached memory on the system, in bytes. This reflects the "cached" column of free command line utility on Linux.

New in 0.2.0
Availability: Linux

psutil.phymem_buffers()

Return the amount of physical memory buffers used by the kernel in bytes. This reflects the "buffers" column of free command line utility on Linux.

New in 0.2.0
Availability: Linux

Constants

psutil.TOTAL_PHYMEM

The amount of total physical memory on the system, in bytes.

psutil.NUM_CPUS

The number of CPUs on the system. This is preferable than using os.environ['NUMBER_OF_PROCESSORS'] as it is more accurate and always available.

psutil.BOOT_TIME

A number indicating the system boot time expressed in seconds since the epoch.

New in 0.2.1

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.

New in 0.2.1
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.get_ionice() and psutil.Process.set_ionice() to get or set process I/O priority. For further information refer to ionice command line utility or ioprio_get system call.

New in 0.2.1
Availability: Linux

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
psutil.STATUS_LOCKED
psutil.STATUS_WAITING

A set of integers representing the status of a process. To be used in conjunction with psutil.Process.status property. If used with str() return a human-readable status string.

New in 0.2.1