pip-audit

pip-audit is a tool for scanning Python environments for packages with known vulnerabilities. It uses the Python Packaging Advisory Database (https://github.com/pypa/advisory-database) via the PyPI JSON API as a source of vulnerability reports.

This project is maintained in part by Trail of Bits with support from Google. This is not an official Google or Trail of Bits product.

Index

• Features
• Installation
  • Third-party packages
  • GitHub Actions
  • pre-commit support
• Usage
  • Environment variables
  • Exit codes
  • Dry runs
• Examples
• Troubleshooting
• Tips and Tricks
• Security model
• Licensing
• Contributing
• Code of Conduct

Features

• Support for auditing local environments and requirements-style files
• Support for multiple vulnerability services (PyPI, OSV)
• Support for emitting SBOMs in CycloneDX XML or JSON
• Support for automatically fixing vulnerable dependencies (--fix)
• Human and machine-readable output formats (columnar, Markdown, JSON)
• Seamlessly reuses your existing local pip caches

Installation

pip-audit requires Python 3.10 or newer, and can be installed directly via pip:

python -m pip install pip-audit

Third-party packages

There are multiple third-party packages for pip-audit. The matrices and badges below list some of them:

In particular, pip-audit can be installed via conda:

conda install -c conda-forge pip-audit

Third-party packages are not directly supported by this project. Please consult your package manager's documentation for more detailed installation guidance.

GitHub Actions

pip-audit has an official GitHub Action!

You can install it from the GitHub Marketplace, or add it to your CI manually:

jobs:
  pip-audit:
    steps:
      - uses: pypa/[email protected]
        with:
          inputs: requirements.txt

See the action documentation for more details and usage examples.

pre-commit support

pip-audit has pre-commit support.

For example, using pip-audit via pre-commit to audit a requirements file:

  - repo: https://github.com/pypa/pip-audit
    rev: v2.10.1
    hooks:
      -   id: pip-audit
          args: ["-r", "requirements.txt"]

ci:
  # Leave pip-audit to only run locally and not in CI
  # pre-commit.ci does not allow network calls
  skip: [pip-audit]

Any pip-audit arguments documented below can be passed.

Usage

You can run pip-audit as a standalone program, or via python -m:

pip-audit --help
python -m pip_audit --help

usage: pip-audit [-h] [-V] [-l] [-r REQUIREMENT] [--locked] [-f FORMAT]
                 [-s SERVICE] [--osv-url OSV_URL] [-d] [-S]
                 [--desc [{on,off,auto}]] [--aliases [{on,off,auto}]]
                 [--cache-dir CACHE_DIR] [--progress-spinner {on,off}]
                 [--timeout TIMEOUT] [--path PATH] [-v] [--fix]
                 [--require-hashes] [--index-url INDEX_URL]
                 [--extra-index-url URL] [--skip-editable] [--no-deps]
                 [-o FILE] [--ignore-vuln ID] [--disable-pip]
                 [project_path]

audit the Python environment for dependencies with known vulnerabilities

positional arguments:
  project_path          audit a local Python project at the given path
                        (default: None)