API Reference

Exceptions

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

Raised when no process with the given PID was 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

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.
  • uid
    The real user id of the current process. Where uid doesn't make sense (Windows) always return -1.
  • gid
    The real group id of the current process. Where gid doesn't make sense (Windows) always return -1.
  • username
    The name of the user that owns the process.
Changed in 2.0: Windows implementation has been rewritten in C for performace and pywin32 extension is no longer required.
  • getcwd()
    Return a string representing the process current working directory.
  • get_num_threads()
    Return the number of threads used by this process.
New in 0.2.0
  • 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.
  • 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 OSX and 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
  • 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 OSX and FreeBSD this is implemented by parsing lsof command output. If lsof is not installed on the system NotImplementedError exception is raised. For third party processes (different than os.getpid()) results can differ depending on user privileges.
New in 0.2.0
  • is_running()
    Return whether the current process is running in the current process list.
  • suspend()
    Suspend process execution.
  • resume()
    Resume process execution.
  • terminate()
    Terminate the process with SIGTERM signal. On Windows this is an alias for kill().
New in 0.2.0
  • 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
  • kill()
    Kill the current process by using SIGKILL signal.
Changed in 0.2.0: no longer accepts sig keyword argument - use send_signal() instead.

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.

psutil.process_iter()

Return an iterator yielding a Process class instances for all running processes on the local machine.

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 CPUTimes class object. 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.TOTAL_PHYMEM
psutil.avail_phymem()
psutil.used_phymem()

Return the amount of total, available and used physical memory on the system, in bytes.

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

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.