nvdlib

0.8.3 verified Mon Apr 27 auth: no python

A Python library for the National Vulnerability Database (NVD) CPE/CVE API. Provides easy search and retrieval of CVEs, CPEs, and CPE match strings with support for pagination and generators. Current version 0.8.3, requires Python >=3.11.0. Maintained actively with monthly releases.

pip install nvdlib

Common errors

error ImportError: cannot import name 'searchCVE' from 'nvdlib' ↓

cause Trying to import searchCVE directly instead of importing the module.

fix

Use 'import nvdlib' then call nvdlib.searchCVE(...)

error nvdlib.error.AuthenticationError: (401) Unauthorized ↓

cause Invalid or missing API key when trying to access API v2.1 endpoints that require key.

fix

Provide a valid API key via the 'key' parameter or set NVD_API_KEY environment variable.

error TypeError: 'NoneType' object is not subscriptable' when accessing CVE attributes ↓

cause Some CVE objects may have missing fields (e.g., 'metrics' or 'descriptions') depending on NVD API response.

fix

Check for None before accessing nested attributes (e.g., if cve.description: ...)

Warnings

gotcha The NVD API has rate limits (5 requests per 30 seconds without API key, 50 per 30 seconds with key). Set 'delay' parameter to at least 0.6 (no key) or 0.03 (with key) seconds between requests to avoid 403 errors. ↓

fix Always pass a 'delay' parameter (e.g., delay=0.6) and consider using an API key via 'key' parameter.

breaking In v0.8.0, boolean parameters 'hasKev', 'hasOval', 'hasCertAlerts', 'hasCertNotes', 'keywordExactMatch' are no longer passed in the URL as 'True'/'False' strings. If you relied on their presence in the URL, behavior changed. ↓

fix Upgrade code to not depend on URL parameter presence for boolean flags; they are now handled internally.

gotcha When using datetime objects for 'pubStartDate' or 'pubEndDate', ensure timezone is set. The library replaces '+' with '%2B', but incorrect timezone strings can cause 404 errors. ↓

fix Use timezone-aware datetime objects (e.g., from datetime import timezone, datetime; dt = datetime.now(timezone.utc)).

gotcha The generator functions searchCVE_V2 and searchCPE_V2 yield results as they fetch pages, but they do not retry on rate limit errors; a single 403 will break the generator. ↓

fix For reliable iteration, collect into list (list(searchCVE_V2(...))) or implement custom retry logic.

Imports

nvdlib
wrong
```
from nvdlib import searchCVE
```
correct
```
import nvdlib
```
Common mistake: trying direct import of functions; they are only available after 'import nvdlib'

Quickstart

Basic usage to search for CVEs by keyword and print ID, score, and title.

import nvdlib
import os

# Use environment variable for API key ( optional but recommended)
api_key = os.environ.get('NVD_API_KEY', '')

# Search for CVEs with keyword
cves = list(nvdlib.searchCVE(keyword='openssl', key=api_key, delay=0.6))
for cve in cves[:2]:
    print(cve.id, cve.score, cve.title)