Skip to main content

A light wrapper around the public VirusTotal API.

Project description

virustotal-python 🐍


A light wrapper around the public VirusTotal API.


  • Written in Python 3.7.
black = "*"
twine = "*"
pytest = "*"

requests = {extras = ["socks"],version = "*"}

Install virustotal-python using either:

  • pip3 install virustotal-python, pipenv install, pip3 install -r requirements.txt, python install.

Example Usage

from virustotal_python import Virustotal
from pprint import pprint

# Normal Initialisation.
vtotal = Virustotal("Insert API Key Here.")

# NEW as of version 0.0.5: Proxy support.
# Example Usage: Using HTTP(S)
vtotal = Virustotal(
    "Insert API Key Here.",
    {"http": "", "https": ""})
# Or using SOCKS
vtotal = Virustotal(
    "Insert API Key Here.",
    {"http": "socks5://user:pass@host:port", "https": "socks5://user:pass@host:port"})

# NOTE: Check for docstrings containing full parameter descriptions.

# Send a file to Virustotal for analysis.
resp = vtotal.file_scan("./")  # PATH to file for querying.

# Retrieve scan report(s) for given file(s) from Virustotal.
# A list containing the resource (SHA256) HASH of a known malicious file.
resp = vtotal.file_report(
# A list of resource(s). Can be `md5/sha1/sha256 hashes` and/or combination of hashes and scan_ids (MAX 4 per standard request rate).
# The first is a scan_id, the second is a SHA256 HASH.
resp = vtotal.file_report(

# Query url(s) to VirusTotal.
# A list containing a url to be scanned by VirusTotal.
resp = vtotal.url_scan([""])  # Query a single url.
# A list of url(s) to be scanned by VirusTotal (MAX 4 per standard request rate).
resp = vtotal.url_scan(
    ["", "", "", ""]

# Retrieve url report(s)
# A list containing the url of the report to be retrieved.
resp = vtotal.url_report([""])  # Query a single url.
# A list of the url(s) and/or scan_id(s) report(s) to be retrieved (MAX 4 per standard request rate).
# The first object in the list is a scan_id.
resp = vtotal.url_report(

# Query an IP to Virustotal.
resp = vtotal.ipaddress_report("")

# Retrieve a domain report.
resp = vtotal.domain_report("")

# Put a comment onto a specific resource.
resp = vtotal.put_comment(
    comment="#watchout, this looks very malicious!",

# Example resp for url_scan().
# Assuming you have already initiated Virustotal() and imported pprint.
resp = vtotal.url_scan([""]) # Query a single url.
{'json_resp': {'permalink': '',
               'resource': '',
               'response_code': 1,
               'scan_date': '2019-02-12 12:10:53',
               'scan_id': 'fd21590d9df715452c8c000e1b5aa909c7c5ea434c2ddcad3f4ccfe9b0ee224e-1549973453',
               'url': '',
               'verbose_msg': 'Scan request successfully queued, come back '
                              'later for the report'},
 'status_code': 200}

Running Tests

  • Navigate to ./virustotal_python/

  • Run the command: pytest -s


  • 0.0.8 - Updated dependencies, removed method file_rescan

  • 0.0.7 - Added tests. Updated dependencies, Updated examples and README, url_report param scan now accepts type(int), no longer type(str)

  • 0.0.6 - Fixed usage example and dependencies in, Setup website, updated requirements.txt.

  • 0.0.5 - Added Proxy support. Via HTTP(S) or using SOCKS: See #8.

  • 0.0.4 - updated; dependencies updated.

  • 0.0.3 - Updated dependencies for urllib3 security vulnerability.

  • 0.0.2 - Changes to file_rescan(), file_report(), url_scan(), url_report() to improve ease of use of the wrapper. See issue #2. Examples updated for changes.

  • 0.0.1 - Inital release of virustotal-python. Covered all endpoints of the Virustotal public API.

Authors -- Contributors


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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for virustotal-python, version 0.0.8
Filename, size File type Python version Upload date Hashes
Filename, size virustotal-python-0.0.8.tar.gz (6.8 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page