You're reading the development version of the psutil docs, which may describe unreleased changes. For the current release see psutil.readthedocs.io/stable.

Install psutil

Linux, Windows, macOS (wheels)

Prebuilt wheels are distributed for these platforms, so you won’t need a C compiler. Install psutil with:

pip install psutil

Inside a virtual environment you can also use uv:

uv pip install psutil

If wheels are not available for your platform or architecture, or you wish to build and install psutil from source, keep reading.

Compile psutil from source

Compiling psutil requires two things: a C compiler and the Python development headers. On Linux, FreeBSD, NetBSD, OpenBSD and Solaris the install-sysdeps.sh script installs the required system dependencies. From an existing Git checkout:

make install-sysdeps

…or run the latest development version of the script directly from GitHub:

curl -fsSL https://raw.githubusercontent.com/giampaolo/psutil/master/scripts/internal/install-sysdeps.sh | sh

Alternatively, install the required dependencies manually as described below, then head to Build and install.

Linux

Debian / Ubuntu:

sudo apt-get install gcc python3-dev

Red Hat / CentOS:

sudo yum install gcc python3-devel

Fedora:

sudo dnf install gcc python3-devel

Arch:

sudo pacman -S gcc python

Alpine:

sudo apk add gcc python3-dev musl-dev linux-headers

Windows

  • To build psutil from source, install Microsoft C++ Build Tools with the Desktop development with C++ option selected.

  • MinGW is not supported.

  • To clone psutil’s Git repository and build or develop it locally, first install Git for Windows and GNU Make. To install GNU Make, open PowerShell and run:

    winget install --exact --id ezwinports.make

  • Close and reopen Git Bash, then follow Build and install.

macOS

Install the Xcode command line tools:

xcode-select --install

FreeBSD

pkg install python312 py312-pip

OpenBSD

export PKG_PATH=https://cdn.openbsd.org/pub/OpenBSD/`uname -r`/packages/`uname -m`/
pkg_add -v python%3 py3-pip

NetBSD

Assuming Python 3.11:

export PKG_PATH="https://cdn.netbsd.org/pub/pkgsrc/packages/NetBSD/`uname -m`/`uname -r`/All"
pkg_add -v pkgin
pkgin update
pkgin install python311 py311-pip

Solaris

pkg install developer/gcc

If cc is unavailable, set CC=gcc when running the commands in Build and install.

AIX

install-sysdeps.sh has no AIX branch. Install a C compiler and the Python development headers from the AIX Toolbox.

Build and install

To build from a Git checkout:

git clone https://github.com/giampaolo/psutil.git
cd psutil
make build
make install

…or download and install the latest source distribution from PyPI:

python -m pip install --no-binary=psutil psutil

Note

By default C source files are compiled in parallel, one job per CPU, which makes building from source 2x to 3.6x faster. Use PSUTIL_BUILD_JOBS to change the number of jobs.

Troubleshooting

Install pip

Python installations normally include pip. If it is missing, first try:

python3 -m ensurepip --upgrade

Some OS-packaged Python installations do not include ensurepip. There, either install the pip package or download get-pip.py and run:

python3 get-pip.py

Permission errors

If you encounter permission errors, install psutil inside a virtual environment instead of modifying the system Python installation:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install psutil