Skip to main content

Best Practices for Using pip

Work inside an isolated environment​

Create one environment per project and verify its interpreter before installing:

python -c "import sys; print(sys.executable)"
python -m pip --version

Avoid sudo pip, global project installs, and flags that bypass an externally managed environment. Those approaches can conflict with the operating system's package manager.

Use explicit package sources​

PyPI is pip's default index. Treat package names, indexes, and archives as software supply-chain inputs:

  • confirm the project and maintainer before installing;
  • prefer TLS-protected, authenticated private indexes where required;
  • do not add an untrusted --extra-index-url casually, because matching names can be selected from more than one index;
  • review dependency changes and test after upgrades.

Separate intent from a snapshot​

Declare the direct dependencies the project needs and the compatible ranges you have tested. pip freeze reports everything installed, including transitive and unrelated packages, so use it as an environment snapshot rather than an automatic statement of project intent.

python -m pip freeze > requirements-lock.txt
python -m pip install -r requirements.txt
python -m pip check

For production or security-sensitive workflows, use an appropriate locking process with hashes and review its generated changes. pip alone does not create a universal cross-platform lock file.

Upgrade deliberately​

Upgrade pip inside the selected virtual environment when a project needs a newer installer:

python -m pip install --upgrade pip

Do not assume every package's newest version is compatible with the rest of a project. Change declared constraints, install into a clean environment, and run tests.