Skip to content
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
Cannot retrieve contributors at this time

psutil development guide

Build, setup and running tests

psutil makes extensive use of C extension modules, meaning a C compiler is required, see install instructions.

Once you have a compiler installed:

git clone
make setup-dev-env  # install useful dev libs (flake8, coverage, ...)
make build
make install
make test
  • make (see Makefile) is the designated tool to run tests, build, install try new features you're developing, etc. This also includes Windows (see make.bat ). Some useful commands are:
make test-parallel   # faster
make test-memleaks
make test-coverage
make lint            # Python (PEP8) and C linters
make uninstall
make help
  • if you're working on a new feature and you wish to compile & test it "on the fly" from a test script, this is a quick & dirty way to do it:
make test  # on UNIX
make test          # on Windows
  • do not use sudo. make install installs psutil as a limited user in "edit" mode, meaning you can edit psutil code on the fly while you develop.
  • if you want to target a specific Python version:
make test PYTHON=python3.5           # UNIX
make test -p C:\python35\python.exe  # Windows

Coding style

  • python code strictly follows PEP-8 styling guides and this is enforced by a commit GIT hook installed via make install-git-hooks which will reject commits if code is not PEP-8 complieant.
  • C code should follow PEP-7 styling guides.

Code organization

psutil/                   # main psutil namespace ("import psutil")
psutil/_ps{platform}.py              # platform-specific python wrapper
psutil/_psutil_{platform}.c          # platform-specific C extension
psutil/tests/test_process|  # main test suite
psutil/tests/test_{platform}.py      # platform-specific test suite

Adding a new API

Typically, this is what you do:

Make a pull request

  • fork psutil (go to and click on "fork")
  • git clone the fork locally: git clone
  • create a branch:git checkout -b new-feature
  • commit your changes: git commit -am 'add some feature'
  • push the branch: git push origin new-feature
  • create a new PR via the GitHub web interface and sign-off your work (see guidelines)

Continuous integration

Unit tests are automatically run on every git push on Linux, macOS, Windows and FreeBSD by using:

OpenBSD, NetBSD, AIX and Solaris does not have continuous test integration.