1.. image:: https://img.shields.io/pypi/dm/psutil.svg
2 :target: https://pypi.python.org/pypi/psutil#downloads
3 :alt: Downloads this month
4
5.. image:: https://api.travis-ci.org/giampaolo/psutil.png?branch=master
6 :target: https://travis-ci.org/giampaolo/psutil
7 :alt: Linux tests (Travis)
8
9.. image:: https://ci.appveyor.com/api/projects/status/qdwvw7v1t915ywr5/branch/master?svg=true
10 :target: https://ci.appveyor.com/project/giampaolo/psutil
11 :alt: Windows tests (Appveyor)
12
13.. image:: https://coveralls.io/repos/giampaolo/psutil/badge.svg?branch=master&service=github
14 :target: https://coveralls.io/github/giampaolo/psutil?branch=master
15 :alt: Test coverage (coverall.io)
16
17.. image:: https://img.shields.io/pypi/v/psutil.svg
18 :target: https://pypi.python.org/pypi/psutil/
19 :alt: Latest version
20
21.. image:: https://img.shields.io/github/stars/giampaolo/psutil.svg
22 :target: https://github.com/giampaolo/psutil/
23 :alt: Github stars
24
25.. image:: https://img.shields.io/scrutinizer/g/giampaolo/psutil.svg
26 :target: https://scrutinizer-ci.com/g/giampaolo/psutil/
27 :alt: Code quality (scrutinizer-ci.com)
28
29.. image:: https://img.shields.io/pypi/l/psutil.svg
30 :target: https://pypi.python.org/pypi/psutil/
31 :alt: License
32
33===========
34Quick links
35===========
36
37- `Home page <https://github.com/giampaolo/psutil>`_
38- `Documentation <http://pythonhosted.org/psutil/>`_
39- `Installation <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`_
40- `Download <https://pypi.python.org/pypi?:action=display&name=psutil#downloads>`_
41- `Forum <http://groups.google.com/group/psutil/topics>`_
42- `Blog <http://grodola.blogspot.com/search/label/psutil>`_
43- `Development guide <https://github.com/giampaolo/psutil/blob/master/DEVGUIDE.rst>`_
44- `What's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst>`_
45
46=======
47Summary
48=======
49
50psutil (python system and process utilities) is a cross-platform library for
51retrieving information on **running processes** and **system utilization**
52(CPU, memory, disks, network) in Python. It is useful mainly for **system
53monitoring**, **profiling and limiting process resources** and **management of
54running processes**. It implements many functionalities offered by command line
55tools such as: ps, top, lsof, netstat, ifconfig, who, df, kill, free, nice,
56ionice, iostat, iotop, uptime, pidof, tty, taskset, pmap. It currently supports
57**Linux, Windows, OSX, FreeBSD** and **Sun Solaris**, both **32-bit** and
58**64-bit** architectures, with Python versions from **2.6 to 3.5** (users of
59Python 2.4 and 2.5 may use `2.1.3 <https://pypi.python.org/pypi?name=psutil&version=2.1.3&:action=files>`__ version).
60`PyPy <http://pypy.org/>`__ is also known to work.
61
62====================
63Example applications
64====================
65
66.. image:: http://psutil.googlecode.com/svn/wiki/images/top-thumb.png
67 :target: http://psutil.googlecode.com/svn/wiki/images/top.png
68 :alt: top
69
70.. image:: http://psutil.googlecode.com/svn/wiki/images/nettop-thumb.png
71 :target: http://psutil.googlecode.com/svn/wiki/images/nettop.png
72 :alt: nettop
73
74.. image:: http://psutil.googlecode.com/svn/wiki/images/iotop-thumb.png
75 :target: http://psutil.googlecode.com/svn/wiki/images/iotop.png
76 :alt: iotop
77
78See also:
79
80 * https://github.com/nicolargo/glances
81 * https://github.com/google/grr
82 * https://github.com/Jahaja/psdash
83
84==============
85Example usages
86==============
87
88CPU
89===
90
91.. code-block:: python
92
93 >>> import psutil
94 >>> psutil.cpu_times()
95 scputimes(user=3961.46, nice=169.729, system=2150.659, idle=16900.540, iowait=629.59, irq=0.0, softirq=19.42, steal=0.0, guest=0, nice=0.0)
96 >>>
97 >>> for x in range(3):
98 ... psutil.cpu_percent(interval=1)
99 ...
100 4.0
101 5.9
102 3.8
103 >>>
104 >>> for x in range(3):
105 ... psutil.cpu_percent(interval=1, percpu=True)
106 ...
107 [4.0, 6.9, 3.7, 9.2]
108 [7.0, 8.5, 2.4, 2.1]
109 [1.2, 9.0, 9.9, 7.2]
110 >>>
111 >>>
112 >>> for x in range(3):
113 ... psutil.cpu_times_percent(interval=1, percpu=False)
114 ...
115 scputimes(user=1.5, nice=0.0, system=0.5, idle=96.5, iowait=1.5, irq=0.0, softirq=0.0, steal=0.0, guest=0.0, guest_nice=0.0)
116 scputimes(user=1.0, nice=0.0, system=0.0, idle=99.0, iowait=0.0, irq=0.0, softirq=0.0, steal=0.0, guest=0.0, guest_nice=0.0)
117 scputimes(user=2.0, nice=0.0, system=0.0, idle=98.0, iowait=0.0, irq=0.0, softirq=0.0, steal=0.0, guest=0.0, guest_nice=0.0)
118 >>>
119 >>> psutil.cpu_count()
120 4
121 >>> psutil.cpu_count(logical=False)
122 2
123 >>>
124
125Memory
126======
127
128.. code-block:: python
129
130 >>> psutil.virtual_memory()
131 svmem(total=8374149120, available=2081050624, percent=75.1, used=8074080256, free=300068864, active=3294920704, inactive=1361616896, buffers=529895424, cached=1251086336)
132 >>> psutil.swap_memory()
133 sswap(total=2097147904, used=296128512, free=1801019392, percent=14.1, sin=304193536, sout=677842944)
134 >>>
135
136Disks
137=====
138
139.. code-block:: python
140
141 >>> psutil.disk_partitions()
142 [sdiskpart(device='/dev/sda1', mountpoint='/', fstype='ext4', opts='rw,nosuid'),
143 sdiskpart(device='/dev/sda2', mountpoint='/home', fstype='ext, opts='rw')]
144 >>>
145 >>> psutil.disk_usage('/')
146 sdiskusage(total=21378641920, used=4809781248, free=15482871808, percent=22.5)
147 >>>
148 >>> psutil.disk_io_counters(perdisk=False)
149 sdiskio(read_count=719566, write_count=1082197, read_bytes=18626220032, write_bytes=24081764352, read_time=5023392, write_time=63199568)
150 >>>
151
152Network
153=======
154
155.. code-block:: python
156
157 >>> psutil.net_io_counters(pernic=True)
158 {'eth0': netio(bytes_sent=485291293, bytes_recv=6004858642, packets_sent=3251564, packets_recv=4787798, errin=0, errout=0, dropin=0, dropout=0),
159 'lo': netio(bytes_sent=2838627, bytes_recv=2838627, packets_sent=30567, packets_recv=30567, errin=0, errout=0, dropin=0, dropout=0)}
160 >>>
161 >>> psutil.net_connections()
162 [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', pid=1254),
163 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', pid=2987),
164 pconn(fd=-1, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=('10.0.0.1', 60759), raddr=('72.14.234.104', 80), status='ESTABLISHED', pid=None),
165 pconn(fd=-1, 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', pid=None)
166 ...]
167 >>>
168 >>> psutil.net_if_addrs()
169 {'lo': [snic(family=<AddressFamily.AF_INET: 2>, address='127.0.0.1', netmask='255.0.0.0', broadcast='127.0.0.1'),
170 snic(family=<AddressFamily.AF_INET6: 10>, address='::1', netmask='ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff', broadcast=None),
171 snic(family=<AddressFamily.AF_LINK: 17>, address='00:00:00:00:00:00', netmask=None, broadcast='00:00:00:00:00:00')],
172 'wlan0': [snic(family=<AddressFamily.AF_INET: 2>, address='192.168.1.3', netmask='255.255.255.0', broadcast='192.168.1.255'),
173 snic(family=<AddressFamily.AF_INET6: 10>, address='fe80::c685:8ff:fe45:641%wlan0', netmask='ffff:ffff:ffff:ffff::', broadcast=None),
174 snic(family=<AddressFamily.AF_LINK: 17>, address='c4:85:08:45:06:41', netmask=None, broadcast='ff:ff:ff:ff:ff:ff')]}
175 >>>
176 >>> psutil.net_if_stats()
177 {'eth0': snicstats(isup=True, duplex=<NicDuplex.NIC_DUPLEX_FULL: 2>, speed=100, mtu=1500),
178 'lo': snicstats(isup=True, duplex=<NicDuplex.NIC_DUPLEX_UNKNOWN: 0>, speed=0, mtu=65536)}
179
180Other system info
181=================
182
183.. code-block:: python
184
185 >>> psutil.users()
186 [user(name='giampaolo', terminal='pts/2', host='localhost', started=1340737536.0),
187 user(name='giampaolo', terminal='pts/3', host='localhost', started=1340737792.0)]
188 >>>
189 >>> psutil.boot_time()
190 1365519115.0
191 >>>
192
193Process management
194==================
195
196.. code-block:: python
197
198 >>> import psutil
199 >>> psutil.pids()
200 [1, 2, 3, 4, 5, 6, 7, 46, 48, 50, 51, 178, 182, 222, 223, 224,
201 268, 1215, 1216, 1220, 1221, 1243, 1244, 1301, 1601, 2237, 2355,
202 2637, 2774, 3932, 4176, 4177, 4185, 4187, 4189, 4225, 4243, 4245,
203 4263, 4282, 4306, 4311, 4312, 4313, 4314, 4337, 4339, 4357, 4358,
204 4363, 4383, 4395, 4408, 4433, 4443, 4445, 4446, 5167, 5234, 5235,
205 5252, 5318, 5424, 5644, 6987, 7054, 7055, 7071]
206 >>>
207 >>> p = psutil.Process(7055)
208 >>> p.name()
209 'python'
210 >>> p.exe()
211 '/usr/bin/python'
212 >>> p.cwd()
213 '/home/giampaolo'
214 >>> p.cmdline()
215 ['/usr/bin/python', 'main.py']
216 >>>
217 >>> p.status()
218 'running'
219 >>> p.username()
220 'giampaolo'
221 >>> p.create_time()
222 1267551141.5019531
223 >>> p.terminal()
224 '/dev/pts/0'
225 >>>
226 >>> p.uids()
227 puids(real=1000, effective=1000, saved=1000)
228 >>> p.gids()
229 pgids(real=1000, effective=1000, saved=1000)
230 >>>
231 >>> p.cpu_times()
232 pcputimes(user=1.02, system=0.31)
233 >>> p.cpu_percent(interval=1.0)
234 12.1
235 >>> p.cpu_affinity()
236 [0, 1, 2, 3]
237 >>> p.cpu_affinity([0]) # set
238 >>>
239 >>> p.memory_percent()
240 0.63423
241 >>>
242 >>> p.memory_info()
243 pmem(rss=7471104, vms=68513792)
244 >>> p.memory_info_ex()
245 extmem(rss=9662464, vms=49192960, shared=3612672, text=2564096, lib=0, data=5754880, dirty=0)
246 >>> p.memory_maps()
247 [pmmap_grouped(path='/lib/x86_64-linux-gnu/libutil-2.15.so', rss=16384, anonymous=8192, swap=0),
248 pmmap_grouped(path='/lib/x86_64-linux-gnu/libc-2.15.so', rss=6384, anonymous=15, swap=0),
249 pmmap_grouped(path='/lib/x86_64-linux-gnu/libcrypto.so.1.0.0', rss=34124, anonymous=1245, swap=0),
250 pmmap_grouped(path='[heap]', rss=54653, anonymous=8192, swap=0),
251 pmmap_grouped(path='[stack]', rss=1542, anonymous=166, swap=0),
252 ...]
253 >>>
254 >>> p.io_counters()
255 pio(read_count=478001, write_count=59371, read_bytes=700416, write_bytes=69632)
256 >>>
257 >>> p.open_files()
258 [popenfile(path='/home/giampaolo/svn/psutil/somefile', fd=3)]
259 >>>
260 >>> p.connections()
261 [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'),
262 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'),
263 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'),
264 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')]
265 >>>
266 >>> p.num_threads()
267 4
268 >>> p.num_fds()
269 8
270 >>> p.threads()
271 [pthread(id=5234, user_time=22.5, system_time=9.2891),
272 pthread(id=5235, user_time=0.0, system_time=0.0),
273 pthread(id=5236, user_time=0.0, system_time=0.0),
274 pthread(id=5237, user_time=0.0707, system_time=1.1)]
275 >>>
276 >>> p.num_ctx_switches()
277 pctxsw(voluntary=78, involuntary=19)
278 >>>
279 >>> p.nice()
280 0
281 >>> p.nice(10) # set
282 >>>
283 >>> p.ionice(psutil.IOPRIO_CLASS_IDLE) # IO priority (Win and Linux only)
284 >>> p.ionice()
285 pionice(ioclass=<IOPriority.IOPRIO_CLASS_IDLE: 3>, value=0)
286 >>>
287 >>> p.rlimit(psutil.RLIMIT_NOFILE, (5, 5)) # set resource limits (Linux only)
288 >>> p.rlimit(psutil.RLIMIT_NOFILE)
289 (5, 5)
290 >>>
291 >>> p.suspend()
292 >>> p.resume()
293 >>>
294 >>> p.terminate()
295 >>> p.wait(timeout=3)
296 0
297 >>>
298 >>> psutil.test()
299 USER PID %CPU %MEM VSZ RSS TTY START TIME COMMAND
300 root 1 0.0 0.0 24584 2240 Jun17 00:00 init
301 root 2 0.0 0.0 0 0 Jun17 00:00 kthreadd
302 root 3 0.0 0.0 0 0 Jun17 00:05 ksoftirqd/0
303 ...
304 giampaolo 31475 0.0 0.0 20760 3024 /dev/pts/0 Jun19 00:00 python2.4
305 giampaolo 31721 0.0 2.2 773060 181896 00:04 10:30 chrome
306 root 31763 0.0 0.0 0 0 00:05 00:00 kworker/0:1
307 >>>
308
309Further process APIs
310====================
311
312.. code-block:: python
313
314 >>> for p in psutil.process_iter():
315 ... print(p)
316 ...
317 psutil.Process(pid=1, name='init')
318 psutil.Process(pid=2, name='kthreadd')
319 psutil.Process(pid=3, name='ksoftirqd/0')
320 ...
321 >>>
322 >>> def on_terminate(proc):
323 ... print("process {} terminated".format(proc))
324 ...
325 >>> # waits for multiple processes to terminate
326 >>> gone, alive = psutil.wait_procs(procs_list, 3, callback=on_terminate)
327 >>>
328
329======
330Donate
331======
332
333A lot of time and effort went into making psutil as it is right now.
334If you feel psutil is useful to you or your business and want to support its future development please consider donating me (`Giampaolo Rodola' <http://grodola.blogspot.com/p/about.html>`_) some money.
335I only ask for a small donation, but of course I appreciate any amount.
336
337.. image:: http://www.paypal.com/en_US/i/btn/x-click-but04.gif
338 :target: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A9ZS7PKKRM3S8
339 :alt: Donate via PayPal
340
341Don't want to donate money? Then maybe you could `write me a recommendation on Linkedin <http://www.linkedin.com/in/grodola>`_.
342
343============
344Mailing list
345============
346
347http://groups.google.com/group/psutil/
348
349========
350Timeline
351========
352
353- 2015-07-15: `psutil-3.1.1.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-3.1.1.tar.gz>`_
354- 2015-07-15: `psutil-3.1.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-3.1.0.tar.gz>`_
355- 2015-06-18: `psutil-3.0.1.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-3.0.1.tar.gz>`_
356- 2015-06-13: `psutil-3.0.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-3.0.0.tar.gz>`_
357- 2015-02-02: `psutil-2.2.1.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-2.2.1.tar.gz>`_
358- 2015-01-06: `psutil-2.2.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-2.2.0.tar.gz>`_
359- 2014-09-26: `psutil-2.1.3.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-2.1.3.tar.gz>`_
360- 2014-09-21: `psutil-2.1.2.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-2.1.2.tar.gz>`_
361- 2014-04-30: `psutil-2.1.1.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-2.1.1.tar.gz>`_
362- 2014-04-08: `psutil-2.1.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-2.1.0.tar.gz>`_
363- 2014-03-10: `psutil-2.0.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-2.0.0.tar.gz>`_
364- 2013-11-25: `psutil-1.2.1.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-1.2.1.tar.gz>`_
365- 2013-11-20: `psutil-1.2.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-1.2.0.tar.gz>`_
366- 2013-11-07: `psutil-1.1.3.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-1.1.3.tar.gz>`_
367- 2013-10-22: `psutil-1.1.2.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-1.1.2.tar.gz>`_
368- 2013-10-08: `psutil-1.1.1.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-1.1.1.tar.gz>`_
369- 2013-09-28: `psutil-1.1.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-1.1.0.tar.gz>`_
370- 2013-07-12: `psutil-1.0.1.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-1.0.1.tar.gz>`_
371- 2013-07-10: `psutil-1.0.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-1.0.0.tar.gz>`_
372- 2013-05-03: `psutil-0.7.1.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.7.1.tar.gz>`_
373- 2013-04-12: `psutil-0.7.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.7.0.tar.gz>`_
374- 2012-08-16: `psutil-0.6.1.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.6.1.tar.gz>`_
375- 2012-08-13: `psutil-0.6.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.6.0.tar.gz>`_
376- 2012-06-29: `psutil-0.5.1.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.5.1.tar.gz>`_
377- 2012-06-27: `psutil-0.5.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.5.0.tar.gz>`_
378- 2011-12-14: `psutil-0.4.1.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.4.1.tar.gz>`_
379- 2011-10-29: `psutil-0.4.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.4.0.tar.gz>`_
380- 2011-07-08: `psutil-0.3.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.3.0.tar.gz>`_
381- 2011-03-20: `psutil-0.2.1.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.2.1.tar.gz>`_
382- 2010-11-13: `psutil-0.2.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.2.0.tar.gz>`_
383- 2010-03-02: `psutil-0.1.3.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.1.3.tar.gz>`_
384- 2009-05-06: `psutil-0.1.2.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.1.2.tar.gz>`_
385- 2009-03-06: `psutil-0.1.1.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.1.1.tar.gz>`_
386- 2009-01-27: `psutil-0.1.0.tar.gz <https://pypi.python.org/packages/source/p/psutil/psutil-0.1.0.tar.gz>`_
387