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.

Common errors

```
pip-audit: command not found
```
cause The `pip-audit` executable is not in the system's PATH, or the tool was not installed correctly in the active environment.

fix Ensure `pip-audit` is installed by running `python -m pip install pip-audit`. If using a virtual environment, make sure it is activated.
```
ModuleNotFoundError: No module named 'pip-audit'
```
cause The `pip-audit` package is not installed in the Python environment currently being used, or the Python interpreter is looking in the wrong location.

fix Activate the correct virtual environment if applicable, and then install `pip-audit` using `pip install pip-audit`.
```
Dependency not found on PyPI and could not be audited: <package_name> (<version>)
```
cause `pip-audit` primarily relies on PyPI for vulnerability information. This error occurs when a package is installed from a private registry, an extra index URL, or has a local version identifier (e.g., `+cpu`) that prevents `pip-audit` from finding its corresponding entry on PyPI.

fix This is often a limitation of `pip-audit`'s default behavior. For such packages, manual vulnerability assessment may be required. While `--extra-index-url` can be passed to `pip-audit`, it may not resolve the issue if the package's exact version or name isn't registered on PyPI itself.
```
ERROR: Could not find a version that satisfies the requirement pip-audit
```
cause The Python version in use does not meet the minimum requirements for `pip-audit` (which is Python 3.9 or newer), or the `pip` installer itself is outdated and cannot resolve compatible versions.

fix Upgrade your Python version to 3.9 or newer. Additionally, ensure `pip` is up-to-date by running `python -m pip install --upgrade pip` before attempting to install `pip-audit`.
```
ModuleNotFoundError: No module named 'filelock'
```
cause This specific `ModuleNotFoundError` (or similar for other internal dependencies like `cyclonedx.parser`) indicates that one of `pip-audit`'s own required packages failed to install correctly or is conflicting within the environment, especially when installed via alternative package managers like Conda.

fix Try creating a fresh virtual environment and reinstall `pip-audit`. If using Conda, explicitly install the missing dependency (e.g., `conda install filelock`) or ensure a clean `pip install pip-audit` within the conda environment.

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 →