API overview

Overview of the entire psutil API (on Linux). This serves as a quick reference to all available functions. For detailed documentation of each function see the full API reference.

Processes

Oneshot

>>> import psutil
>>>
>>> p = psutil.Process(7055)
>>> with p.oneshot():
...     p.name()
...     p.cpu_times()
...     p.memory_info()
...
'python3'
pcputimes(user=1.02, system=0.31, children_user=0.32, children_system=0.1, iowait=0.0)
pmem(rss=3164160, vms=4410163, shared=897433, text=302694, data=2422374)
>>>

Identity

>>> import psutil
>>>
>>> p = psutil.Process(7055)
>>> p
psutil.Process(pid=7055, name='python3', status=<ProcessStatus.STATUS_RUNNING: 'running'>, started='09:04:44')
>>> p.pid
7055
>>>
>>> p.name()
'python3'
>>>
>>> p.exe()
'/usr/bin/python3'
>>>
>>> p.cwd()
'/home/giampaolo'
>>>
>>> p.cmdline()
['/usr/bin/python3', 'main.py']
>>>
>>> p.status()
<ProcessStatus.STATUS_RUNNING: 'running'>
>>>
>>> p.create_time()
1267551141.5019531
>>>
>>> p.terminal()
'/dev/pts/0'
>>>
>>> p.environ()
{'GREP_OPTIONS': '--color=auto',
 'LC_PAPER': 'it_IT.UTF-8',
 'SHELL': '/bin/bash',
 'XDG_CONFIG_DIRS': '/etc/xdg/xdg-ubuntu:/usr/share/upstart/xdg:/etc/xdg',
 ...}
>>>
>>> p.is_running()
True
>>>
>>> p.as_dict()
{'num_ctx_switches': pctxsw(voluntary=63, involuntary=1),
 'pid': 5457,
 'status': <ProcessStatus.STATUS_RUNNING: 'running'>,
 ...}
>>>

Process tree

>>> p.ppid()
7054
>>> p.parent()
psutil.Process(pid=4699, name='bash', status=<ProcessStatus.STATUS_SLEEPING: 'sleeping'>, started='09:06:44')
>>>
>>> p.parents()
[psutil.Process(pid=4699, name='bash', started='09:06:44'),
 psutil.Process(pid=4689, name='gnome-terminal-server', status=<ProcessStatus.STATUS_SLEEPING: 'sleeping'>, started='0:06:44'),
 psutil.Process(pid=1, name='systemd', status=<ProcessStatus.STATUS_SLEEPING: 'sleeping'>, started='05:56:55')]
>>>
>>> p.children(recursive=True)
[psutil.Process(pid=29835, name='python3', status=<ProcessStatus.STATUS_SLEEPING: 'sleeping'>, started='11:45:38'),
 psutil.Process(pid=29836, name='python3', status=<ProcessStatus.STATUS_WAKING: 'waking'>, started='11:43:39')]
>>>

Credentials

>>> p.username()
'giampaolo'
>>> p.uids()
puids(real=1000, effective=1000, saved=1000)
>>> p.gids()
pgids(real=1000, effective=1000, saved=1000)
>>>

CPU / scheduling

>>> p.cpu_times()
pcputimes(user=1.02, system=0.31, children_user=0.32, children_system=0.1, iowait=0.0)
>>>
>>> p.cpu_percent(interval=1.0)
12.1
>>>
>>> p.cpu_affinity()
[0, 1, 2, 3]
>>> p.cpu_affinity([0, 1])  # set
>>>
>>> p.cpu_num()
1
>>>
>>> p.num_ctx_switches()
pctxsw(voluntary=78, involuntary=19)
>>>
>>> p.nice()
0
>>> p.nice(10)  # set
>>>
>>> p.ionice(psutil.IOPRIO_CLASS_IDLE)  # set IO priority
>>> p.ionice()
pionice(ioclass=<ProcessIOPriority.IOPRIO_CLASS_IDLE: 3>, value=0)
>>>
>>> p.rlimit(psutil.RLIMIT_NOFILE, (5, 5))  # set resource limits
>>> p.rlimit(psutil.RLIMIT_NOFILE)
(5, 5)
>>>

Memory

>>> p.memory_info()
pmem(rss=3164160, vms=4410163, shared=897433, text=302694, data=2422374)
>>>
>>> p.memory_info_ex()
pmem_ex(rss=3164160,
        vms=4410163,
        shared=897433,
        text=302694,
        data=2422374,
        peak_rss=4172190,
        peak_vms=6399001,
        rss_anon=2266726,
        rss_file=897433,
        rss_shmem=0,
        swap=0,
        hugetlb=0)
>>>
>>> p.memory_percent()
0.7823
>>>
>>> p.memory_footprint()  # "real" USS memory usage
pfootprint(uss=2355200, pss=2483712, swap=0)
>>>
>>> p.memory_maps()
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='[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),
...]
>>>
>>> p.page_faults()
ppagefaults(minor=5905, major=3)
>>>

Threads

>>> p.threads()
[pthread(id=5234, user_time=22.5, system_time=9.2891),
 pthread(id=5237, user_time=0.0707, system_time=1.1)]
>>> p.num_threads()
4
>>>

Files and connections

>>> p.io_counters()
pio(read_count=478001,
    write_count=59371,
    read_bytes=700416,
    write_bytes=69632,
    read_chars=456232,
    write_chars=517543)
>>>
>>> p.open_files()
[popenfile(path='/home/giampaolo/monit.py', fd=3, position=0, mode='r', flags=32768),
 popenfile(path='/var/log/monit.log', fd=4, position=235542, mode='a', flags=33793)]
>>>
>>> p.net_connections(kind='tcp')
[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=<ConnectionStatus.CONN_ESTABLISHED: '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=<ConnectionStatus.CONN_CLOSING: 'CLOSING'>)]
>>>
>>> p.num_fds()
8
>>>

Signals

>>> p.send_signal(signal.SIGTERM)
>>> p.suspend()
>>> p.resume()
>>> p.terminate()
>>> p.kill()
>>> p.wait(timeout=3)
<NegSignal.SIGTERM: -15>
>>>

Other process functions

>>> import psutil
>>>
>>> psutil.pids()
[1, 2, 3, 4, 5, 6, 7, 46, 48, 50, 51, 178, 182, ...]
>>>
>>> psutil.pid_exists(3)
True
>>>
>>> for p in psutil.process_iter(['pid', 'name']):
...     print(p.pid, p.name())
...
1 systemd
2 kthreadd
3 ksoftirqd/0
...
>>>
>>> def on_terminate(proc):
...     print("process {} terminated".format(proc))
...
>>> # waits for multiple processes to terminate
>>> gone, alive = psutil.wait_procs(procs_list, timeout=3, callback=on_terminate)
>>>

C heap introspection

>>> import psutil
>>>
>>> psutil.heap_info()
pheap(heap_used=5177792, mmap_used=819200)
>>>
>>> psutil.heap_trim()
>>>

See also psleak.

Windows services

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