We’re pleased that you are interested in working on pip.
This document is meant to get you setup to work on pip and to act as a guide and reference to the development setup. If you face any issues during this process, please open an issue about it on the issue tracker.
Get the source code¶
To work on pip, you first need to get the source code of pip. The source code is available on GitHub.
$ git clone https://github.com/pypa/pip $ cd pip
pip is a command line application written in Python. For developing pip, you should install Python on your computer.
For developing pip, you need to install tox. Often, you can run
python -m pip install tox to install and use it.
Running pip From Source Tree¶
To run the pip executable from your source tree during development, install pip locally using editable installation (inside a virtualenv). You can then invoke your local source tree pip normally.
virtualenv .venv # You can also use "python -m venv .venv" source .venv/bin/activate python -m pip install -e . python -m pip --version
virtualenv .venv # You can also use "py -m venv .venv" .venv\Scripts\activate py -m pip install -e . py -m pip --version
It is preferable to run the tests in parallel for better experience during development, since the tests can take a long time to finish when run sequentially.
To run tests:
$ tox -e py36 -- -n auto
To run tests without parallelization, run:
$ tox -e py36
The example above runs tests against Python 3.6. You can also use other
tox has been configured to forward any additional arguments it is given to
pytest. This enables the use of pytest’s rich CLI. As an example, you
can select tests using the various ways that pytest provides:
$ # Using file name $ tox -e py36 -- tests/functional/test_install.py $ # Using markers $ tox -e py36 -- -m unit $ # Using keywords $ tox -e py36 -- -k "install and not wheel"
Running pip’s test suite requires supported version control tools (subversion, bazaar, git, and mercurial) to be installed. If you are missing one of the VCS tools, you can tell pip to skip those tests:
$ tox -e py36 -- -k "not svn" $ tox -e py36 -- -k "not (svn or git)"
pip uses pre-commit for managing linting of the codebase.
pre-commit performs various checks on all files in pip and uses tools that
help follow a consistent code style within the codebase.
To use linters locally, run:
$ tox -e lint
# noqa comments to suppress linter warnings - wherever
possible, warnings should be fixed instead.
# noqa comments are
reserved for rare cases where the recommended style causes severe
Running pip under a debugger¶
In order to debug pip’s behavior, you can run it under a debugger like so:
$ python -m pdb -m pip --debug ...
... with arguments you’d like to run pip with. Give PDB the
c (“continue”) command afterwards, to run the process.
--debug flag disables pip’s exception handler, which would normally
catch all unhandled exceptions. With this flag, pip will let these exceptions
propagate outside of its main subroutine, letting them get caught by the
debugger. This way you’ll be able to debug an exception post-mortem via PDB.
pip’s documentation is built using Sphinx. The documentation is written in reStructuredText.
To build it locally, run:
$ tox -e docs
The built documentation can be found in the
For each Pull Request made the documentation is deployed following this link:
The following pages may be helpful for new contributors on where to look next in order to start contributing.