virustotal-python 🐍

A Python library to interact with the public VirusTotal v3 and v2 APIs.

This library is intended to be used with the public VirusTotal APIs. However, it could be used to interact with premium API endpoints as well.

It is highly recommended that you use the VirusTotal v3 API as it is the "default and encouraged way to programmatically interact with VirusTotal".

Installation 🛠

# PyPi
pip install virustotal-python
# Manually
pip install .# uv
uv sync --no-dev

Get a VirusTotal API Key 🔑

Sign up for a VirusTotal account. Then, view your VirusTotal API key.

Getting Started

importvirustotal_pythonwithvirustotal_python.Virustotal("<VirusTotal API Key>") asvtotal:
# Your code here...# Use the (old) VirusTotal version 2 APIwithvirustotal_python.Virustotal(
API_KEY="<VirusTotal API Key>", API_VERSION=2
) asvtotal:
# Your code here...# You can also set proxies and timeouts for requests made by the library# NOTE: To use proxies, you must have the PySocks extra installedwithvirustotal_python.Virustotal(
API_KEY="<VirusTotal API Key>",
PROXIES={"http": "http://10.10.1.10:3128", "https": "https://10.10.1.10:1080"},
TIMEOUT=5.0,
) asvtotal:
# Your code here...# You can also omit the API_KEY parameter and provide your# API key via the environment variable VIRUSTOTAL_API_KEY# Bash: export VIRUSTOTAL_API_KEY="<VirusTotal API Key>"# PowerShell: $Env:VIRUSTOTAL_API_KEY = "<VirusTotal API Key>"# Then...withvirustotal_python.Virustotal() asvtotal:
# Your code here...

Code Snippets

Further usage examples can be found in examples.

Send a file for analysis 🔎

importvirustotal_pythonimportos.pathfrompprintimportpprintFILE_PATH="/path/to/file/to/scan.txt"# Create dictionary containing the file to send for multipart encoding uploadfiles= {"file": (os.path.basename(FILE_PATH), open(os.path.abspath(FILE_PATH), "rb"))}
withvirustotal_python.Virustotal("<VirusTotal API Key>") asvtotal:
resp=vtotal.request("files", files=files, method="POST")
pprint(resp.json())

Get information about a file 📁

importvirustotal_pythonfrompprintimportpprint# The ID (either SHA-256, SHA-1 or MD5 hash) identifying the fileFILE_ID="9f101483662fc071b7c10f81c64bb34491ca4a877191d464ff46fd94c7247115"withvirustotal_python.Virustotal("<VirusTotal API Key>") asvtotal:
resp=vtotal.request(f"files/{FILE_ID}")
pprint(resp.data)

Send a URL 🔗 for analysis and get the report 📄

importvirustotal_pythonfrompprintimportpprintfrombase64importurlsafe_b64encodeurl="ihaveaproblem.info"withvirustotal_python.Virustotal("<VirusTotal API Key>") asvtotal:
try:
resp=vtotal.request("urls", data={"url": url}, method="POST")
# Safe encode URL in base64 format# https://developers.virustotal.com/reference/urlurl_id=urlsafe_b64encode(url.encode()).decode().strip("=")
report=vtotal.request(f"urls/{url_id}")
pprint(report.object_type)
pprint(report.data)
exceptvirustotal_python.VirustotalErroraserr:
print(f"Failed to send URL: {url} for analysis and get the report: {err}")

Get information about a domain:

importvirustotal_pythonfrompprintimportpprintdomain="virustotal.com"withvirustotal_python.Virustotal("<VirusTotal API Key>") asvtotal:
resp=vtotal.request(f"domains/{domain}")
pprint(resp.data)

Development

Black is used for code formatting.

Unit Tests

To run the unit tests, run pytest from the root of the project:

uv sync --dev
uv run pytest --cov=virustotal_python

Publishing a new release

# Run from the master branchexport VERSION=x.x.x
git commit --allow-empty -m "Publish $VERSION"
git tag -a $VERSION -m "Version $VERSION"
git push --tags

Authors & Contributors

• dbrennand - Author

• smk762 - Contributor

Changelog

See the CHANGELOG for details.

License

This project is licensed under the MIT License - see the LICENSE for details.