psutil README

The project's README from github.com/giampaolo/psutil. As one markdown file: README.md.

..

.. raw:: html

<div align="center">
    <a href="https://github.com/giampaolo/psutil"><img src="https://github.com/giampaolo/psutil/raw/master/docs/_static/images/logo-psutil-readme.svg" alt="psutil" /></a>
    <p align="center">Process and System Utilities for Python</p>
    <a href="https://psutil.io/"><b>Documentation</b></a>&nbsp;&nbsp;&nbsp;
    <a href="https://psutil.io/blog/"><b>Blog</b></a>&nbsp;&nbsp;&nbsp;
    <a href="https://psutil.io/adoption/"><b>Who uses psutil</b></a>&nbsp;&nbsp;&nbsp;
</div>

<br/>

<div align="center">
  <a href="https://clickpy.clickhouse.com/dashboard/psutil"><img src="https://static.pepy.tech/badge/psutil/month" alt="Downloads"></a>

  <a href="https://repology.org/metapackage/python:psutil/versions"><img src="https://repology.org/badge/tiny-repos/python:psutil.svg" alt="Binary packages"></a>

  <a href="https://pypi.org/project/psutil"><img src="https://img.shields.io/pypi/v/psutil.svg?label=pypi&color=yellowgreen" alt="Latest version"></a>
</div>

<div align="center">
  <a href="https://github.com/giampaolo/psutil/actions?query=workflow%3Atests"><img src="https://img.shields.io/github/actions/workflow/status/giampaolo/psutil/.github/workflows/tests.yml.svg?label=Linux%2C%20macOS%2C%20Win" alt="Linux, macOS, Windows"></a>

  <a href="https://github.com/giampaolo/psutil/actions?query=workflow%3Absd"><img src="https://img.shields.io/github/actions/workflow/status/giampaolo/psutil/.github/workflows/bsd.yml.svg?label=BSD" alt="FreeBSD, NetBSD, OpenBSD"></a>

  <a href="https://github.com/giampaolo/psutil/actions?query=workflow%3Adocs"><img src="https://img.shields.io/github/actions/workflow/status/giampaolo/psutil/.github/workflows/docs.yml.svg?label=docs" alt="Documentation"></a>
</div>

..

About

psutil is a cross-platform library for retrieving information about running processes and system utilization (CPU, memory, disks, network, sensors) in Python. It is useful mainly for system monitoring, profiling, limiting process resources, and managing running processes. It implements many functionalities offered by UNIX command line tool such as ps, top, free, iotop, netstat, ifconfig, lsof and others (see shell equivalents_). Psutil supports the following platforms:

Adoption

psutil is among the top 100 <https://clickpy.clickhouse.com/dashboard/psutil>__ most-downloaded packages on PyPI, with 390+ million downloads per month and 780,000+ GitHub repositories <https://github.com/giampaolo/psutil/network/dependents>__ using it. See also adoptions <https://psutil.io/adoption/>__ and alternatives <https://psutil.io/alternatives/>__.

Install

.. code-block::

pip install psutil

For platform-specific details see installation <https://psutil.io/install/>_.

Documentation

psutil documentation is available at https://psutil.io.

..

Sponsors

.. raw:: html

<table border="0" cellpadding="10" cellspacing="0" class="sponsor-table">
  <tr>
    <td align="center" style="vertical-align: middle;">
      <a href="https://tidelift.com/subscription/pkg/pypi-psutil?utm_source=pypi-psutil&utm_medium=referral&utm_campaign=readme"><img width="160" src="https://raw.githubusercontent.com/giampaolo/psutil/refs/heads/master/docs/_static/images/logo-tidelift.svg" class="sponsor-logo"></a>
    </td>
    <td align="center" style="vertical-align: middle;">
      <a href="https://sansec.io/"><img width="145" src="https://raw.githubusercontent.com/giampaolo/psutil/refs/heads/master/docs/_static/images/logo-sansec.svg" class="sponsor-logo"></a>
    </td>
    <td align="center" style="vertical-align: middle;">
      <a href="https://www.apivoid.com/"><img width="130" src="https://raw.githubusercontent.com/giampaolo/psutil/refs/heads/master/docs/_static/images/logo-apivoid.svg" class="sponsor-logo"></a>
    </td>
  </tr>
</table>

<div style="text-align: center;"><sup><a href="https://psutil.io/funding/">add your logo</a></sup></div>

..

Example usages

For the full API with more examples, see the API overview <https://psutil.io/api-overview/>_ and API reference <https://psutil.io/api/>_.

CPU

.. code-block:: python

>>> import psutil
>>> psutil.cpu_percent(interval=1, percpu=True)
[4.0, 6.9, 3.7, 9.2]
>>> psutil.cpu_count(logical=False)
2
>>> psutil.cpu_freq()
scpufreq(current=931.42, min=800.0, max=3500.0)

Memory

.. code-block:: python

>>> psutil.virtual_memory()
svmem(total=10367352832, available=6472179712, percent=37.6, used=8186245120, free=2181107712, ...)
>>> psutil.swap_memory()
sswap(total=2097147904, used=296128512, free=1801019392, percent=14.1, sin=304193536, sout=677842944)

Disks

.. code-block:: python

>>> psutil.disk_partitions()
[sdiskpart(device='/dev/sda1', mountpoint='/', fstype='ext4', opts='rw,nosuid'),
 sdiskpart(device='/dev/sda2', mountpoint='/home', fstype='ext', opts='rw')]
>>> psutil.disk_usage('/')
sdiskusage(total=21378641920, used=4809781248, free=15482871808, percent=22.5)

Network

.. code-block:: python

>>> psutil.net_io_counters(pernic=True)
{'eth0': netio(bytes_sent=485291293, bytes_recv=6004858642, ...),
 'lo': netio(bytes_sent=2838627, bytes_recv=2838627, ...)}
>>> psutil.net_connections(kind='tcp')
[sconn(fd=115, family=2, type=1, laddr=addr(ip='10.0.0.1', port=48776), raddr=addr(ip='93.186.135.91', port=80), status='ESTABLISHED', pid=1254),
 ...]

Sensors

.. code-block:: python

>>> psutil.sensors_temperatures()
{'coretemp': [shwtemp(label='Physical id 0', current=52.0, high=100.0, critical=100.0),
              shwtemp(label='Core 0', current=45.0, high=100.0, critical=100.0)]}
>>> psutil.sensors_battery()
sbattery(percent=93, secsleft=16628, power_plugged=False)

Processes

.. code-block:: python

>>> p = psutil.Process(7055)
>>> p.name()
'python3'
>>> p.exe()
'/usr/bin/python3'
>>> p.cpu_percent(interval=1.0)
12.1
>>> p.memory_info()
pmem(rss=3164160, vms=4410163, shared=897433, text=302694, data=2422374)
>>> p.net_connections(kind='tcp')
[pconn(fd=115, family=2, type=1, laddr=addr(ip='10.0.0.1', port=48776), raddr=addr(ip='93.186.135.91', port=80), status='ESTABLISHED')]
>>> p.open_files()
[popenfile(path='/home/giampaolo/monit.py', fd=3, position=0, mode='r', flags=32768)]
>>>
>>> for p in psutil.process_iter(['pid', 'name']):
...     print(p.pid, p.name())
...
1 systemd
2 kthreadd
3 ksoftirqd/0
...

.. _shell equivalents: https://psutil.io/shell-equivalents/

..

License

BSD-3

psutil (giampaolo/psutil)

system-monitor
Searching Database…

11.3K ·GitHub
Psutil
What is this?psutil is a cross-platform Python library for retrieving information about running processes and system utilization: CPU, memory, disks, network and sensors.
Is it a library or a standalone tool?It is a Python library you import and call from your own code, not a standalone app with a UI; it reimplements functionality of CLI tools like ps, top, free, iotop, netstat, ifconfig and lsof.
How do I add it to a project?Install it with pip (pip install psutil) and import psutil in your Python code; no build step or external services are required.
Do I need anything besides Python?No, psutil is self-contained; it has no listed third-party dependencies in the repo.
Does every function work the same on every OS?Not stated explicitly in this README excerpt, but the breadth of supported platforms (including niche Unixes) implies some functions are OS-specific or have platform caveats.
Which operating systems does it support?It runs on Linux, Windows, macOS, FreeBSD/OpenBSD/NetBSD, Sun Solaris and AIX.
Can I get CPU usage per core?Yes, psutil.cpu_percent(interval=1, percpu=True) returns a list of per-core usage percentages.
Can I inspect a specific process by PID?Yes, psutil.Process(pid) gives access to name, executable path, CPU/memory usage, open files and network connections of that process.
Can I check battery or temperature sensors?Yes, psutil.sensors_temperatures() and psutil.sensors_battery() expose hardware sensor readings where available on the platform.
Can I list disk partitions and usage?Yes, psutil.disk_partitions() lists mounted partitions and psutil.disk_usage(path) returns total/used/free space for a given path.
What are similar projects?stats, glances, gopsutil, nodelume, bpytop, hotpath-rs, node_exporter, telegraf
Which topics is it in?sensors, cpu, system-monitor, network, memory, sysadmin, observability, bsd, dashboard, monitoring, devops, networking
Creator
giampaolo
Size
40.3 MB
Stars
11.3K
Updated
CommitOct 17
Age
12y
Commits · 90 Days