pip-audit

2.10.0 · active · verified Thu Apr 09

pip-audit is a command-line tool for scanning Python environments (installed packages, requirements files, or lockfiles) for known vulnerabilities. It leverages various vulnerability databases like OSV and Ecosyste.ms to provide comprehensive security checks. Currently at version 2.10.0, it maintains an active development pace with frequent minor releases to introduce new features, fix bugs, and update dependencies.

Warnings

breaking The minimum required Python version has progressively increased. As of v2.10.0, Python >=3.10 is required. Earlier versions (v2.8.0 onwards required >=3.9, v2.6.2 onwards required >=3.8) supported older Python versions.
Fix: Ensure your environment uses Python 3.10 or newer for v2.10.0+. Consult `pip-audit`'s changelog for specific version requirements if using an older `pip-audit` release.
gotcha Users resolving packages against private package indexes that require authentication might experience hangs. This was a recurring issue with `pip` subprocess invocation.
Fix: Upgrade to `pip-audit` v2.7.2 or newer, which includes fixes for authentication-related hangs and improves `pip`'s keyring provider usage. Ensure `keyring` is properly configured if using authenticated indices.
gotcha `pip-audit`'s default cache locations on macOS and Linux changed in v2.8.0 to align with platform-specific caching directory idioms (e.g., XDG).
Fix: Be aware that cache files created by older `pip-audit` versions might not be recognized by newer versions in their new default locations. Manually clear or relocate old cache data if issues arise, or specify `--cache-dir` for explicit control.
gotcha On Windows, some versions experienced crashes or issues related to temporary file handling and subprocess deadlocks.
Fix: Upgrade to `pip-audit` v2.7.3 or newer to benefit from improved handling of temporary files and subprocesses on Windows, addressing crashes and deadlocks.

Install

pip install pip-audit Install pip-audit

Imports

audit_environment
```
from pip_audit._api import audit_environment
```
Primarily a CLI tool, but offers programmatic API for auditing an installed environment.
audit_requirements
```
from pip_audit._api import audit_requirements
```
Use this for auditing a list of Pip-style requirements.
main
```
from pip_audit._cli import main
```
The entry point for the command-line interface. Rarely called directly in user code.

Quickstart

This quickstart demonstrates how to use `pip-audit` via its command-line interface, which is its primary mode of operation. It shows scanning the current Python environment and a requirements file, outputting results in JSON format for machine readability. The `subprocess` module is used to simulate a command-line invocation.

import subprocess

# Scan the current Python environment
print('Scanning current environment:')
result_env = subprocess.run(['pip-audit', '--output-format', 'json'], capture_output=True, text=True, check=False)
print(result_env.stdout)

# Example: Scan a requirements file (create a dummy one)
with open('requirements.txt', 'w') as f:
    f.write('requests==2.25.1\n') # Known vulnerable version

print('\nScanning requirements.txt:')
result_req = subprocess.run(['pip-audit', '-r', 'requirements.txt', '--output-format', 'json'], capture_output=True, text=True, check=False)
print(result_req.stdout)

view raw JSON →