Python pip-audit Dependency Security Scanning

pip-audit scans Python environments and requirements files for packages with known vulnerabilities. It queries the Python Packaging Advisory Database via the PyPI JSON API and the OSV database, reporting CVEs, GHSA IDs, and fix versions.

Installation

Install pip-audit into the project's virtual environment or as a standalone tool:

Into active virtual environment

pip install pip-audit

Isolated global install (preferred for CI)

pipx install pip-audit

Via conda

conda install -c conda-forge pip-audit

pip-audit requires Python 3.10 or newer.

Core Usage

Audit the current environment:

pip-audit

Audit a requirements file:

pip-audit -r requirements.txt

Audit a local Python project (reads pyproject.toml or pylock.*.toml ):

pip-audit .

Audit lock files only:

pip-audit --locked .

Exclude system packages (useful inside virtual environments):

pip-audit -r requirements.txt -l

Vulnerability Services

pip-audit supports two vulnerability data sources:

Service Flag Default

PyPI JSON API -s pypi

Yes

OSV (Open Source Vulnerabilities) -s osv

No

Use OSV for broader advisory coverage across multiple ecosystems:

pip-audit -r requirements.txt -s osv

Switch the OSV API endpoint (e.g., for self-hosted instances):

pip-audit -r requirements.txt -s osv --osv-url https://api.osv.dev/v1/query

Output Formats

pip-audit -f columns # Default columnar output pip-audit -f json # Machine-readable JSON pip-audit -f markdown # Markdown table pip-audit -f cyclonedx-json # CycloneDX SBOM (JSON) pip-audit -f cyclonedx-xml # CycloneDX SBOM (XML)

Save output to a file:

pip-audit -f json -o audit-report.json

Include vulnerability descriptions and alias IDs (CVE/GHSA) in output:

pip-audit --desc --aliases

For JSON format, descriptions and aliases are included automatically.

Automatic Fix

Upgrade vulnerable packages automatically:

pip-audit --fix

Preview what would be upgraded without applying changes:

pip-audit --fix --dry-run

Dry run without the --fix flag reports how many dependencies would be audited:

pip-audit --dry-run

Ignoring Specific Vulnerabilities

Suppress known false positives or accepted risks using the vulnerability ID, CVE, or GHSA alias:

Ignore by PYSEC ID

pip-audit --ignore-vuln PYSEC-2021-666

Ignore by CVE

pip-audit --ignore-vuln CVE-2019-1010083

Ignore by GHSA

pip-audit --ignore-vuln GHSA-w596-4wvx-j9j6

Ignore multiple

pip-audit --ignore-vuln CVE-XXX-YYYY --ignore-vuln GHSA-abc-def-ghij

Document every suppressed ID in a comment or issue tracker entry explaining why it is not applicable.

Performance: Skipping Dependency Resolution

pip-audit performs its own dependency resolution by default, which can be slow. Skip resolution when inputs are already fully pinned:

Pinned without hashes (faster):

pip-audit --no-deps -r requirements.txt

Pinned with hashes (fastest, most secure):

pip-audit --require-hashes -r requirements.txt

--require-hashes is equivalent to pip's hash-checking mode. It fails if any package is missing a hash, providing additional supply-chain integrity.

Audit a pre-installed environment directly (no resolution needed):

pip-audit pip-audit --local # only local packages, skip globally installed

Exit Codes

Code Meaning

0

No known vulnerabilities found

1

One or more vulnerabilities found

Exit codes cannot be suppressed internally. Use shell idioms when needed:

Continue even if vulnerabilities found

pip-audit || true

Capture for custom handling

pip-audit exitcode="${?}"

Environment Variables

Configure pip-audit without flags for CI pipelines:

Variable Equivalent flag Example value

PIP_AUDIT_FORMAT

--format

json

PIP_AUDIT_VULNERABILITY_SERVICE

--vulnerability-service

osv

PIP_AUDIT_DESC

--desc

off

PIP_AUDIT_PROGRESS_SPINNER

--progress-spinner

off

PIP_AUDIT_OUTPUT

--output

audit-report.json

Reporting Only Fixable Vulnerabilities

Filter to only fail when vulnerabilities have known fix versions using jq :

test -z "$(pip-audit -r requirements.txt --format=json 2>/dev/null
| jq '.dependencies[].vulns[].fix_versions[]')"

This exits non-zero only when at least one fixable vulnerability exists.

pipenv Projects

Convert Pipfile.lock to a requirements format and pipe directly:

pipenv run pip-audit -r <(pipenv requirements)

Private Package Indices

Use --index-url and --extra-index-url to point at internal registries:

pip-audit -r requirements.txt
--index-url https://pypi.example.com/simple/
--extra-index-url https://pypi.org/simple/

Interactive authentication is not supported. Use keyring via the subprocess provider or set credentials in the URL or environment.

Security Model

pip-audit detects known vulnerabilities in direct and transitive Python dependencies. It does not:

• Perform static code analysis

• Detect vulnerabilities in native shared libraries linked by Python packages

• Protect against malicious packages not yet in any advisory database

Treat pip-audit -r INPUT as equivalent to pip install -r INPUT — it resolves and downloads packages. Only audit inputs from trusted sources.

Additional Resources

• references/ci-integration.md — GitHub Actions workflow, pre-commit hook, and baseline automation patterns