VirusTotal Python Client Library

Warnings

• breaking Python 3.7 support was officially dropped in `vt-py` version 0.21.0. Users on Python 3.7 or older will need to upgrade their Python version or pin `vt-py` to a version prior to 0.21.0.
  Fix: Upgrade Python to 3.8 or newer, or downgrade `vt-py` to `<0.21.0`.
• breaking In `vt-py` v0.20.0, the `WhistleBlowerDict` (a subclass of `collections.UserDict`) used internally for `vt.Object` attributes was converted to a plain Python `dict`. Code relying on `UserDict` specific behaviors or encountering 'Object of type WhistleBlowerDict is not JSON serializable' errors in older versions should be updated.
  Fix: Update code to treat `vt.Object` attributes as standard dictionaries. If on older versions, ensure attributes are explicitly converted or accessed as plain dicts before serialization.
• gotcha The `vt-py` library is built around `asyncio`. Running client methods in synchronous code or within existing event loops (e.g., in some web frameworks or cloud functions) without proper `asyncio` context can lead to `RuntimeError: There is no current event loop in thread...` errors.
  Fix: Ensure `vt-py` asynchronous calls are executed within an `asyncio` event loop. For standalone scripts, use `asyncio.run()`. For integration into existing sync applications, consider `nest_asyncio` or carefully manage event loop contexts.
• gotcha It is crucial to explicitly close the `vt.Client` instance to release underlying network resources (like TCP connections) when it's no longer needed. Not doing so can lead to resource leaks and potential runtime warnings/errors.
  Fix: Always use the client within an `async with vt.Client(...)` block, which handles automatic closing, or explicitly call `await client.close()` after all operations are complete.
• gotcha The `vt-py` library is designed as a relatively low-level wrapper around the VirusTotal API v3. Users are expected to have a good understanding of the VirusTotal API v3 concepts and REST endpoint paths, as the library mirrors the API structure rather than providing a high level of abstraction.
  Fix: Familiarize yourself with the official VirusTotal API v3 documentation to understand endpoints, object structures, and request/response formats when using `vt-py`.

Install

• pip install vt-py Install stable version

Imports

• Client
  wrong:

  from vt.client import Client

  correct:

  import vt
  client = vt.Client(api_key)

  The common pattern shown in documentation is to import the top-level 'vt' module and access Client via 'vt.Client'.
• url_id
  wrong:

  from vt.client import url_id

  correct:

  import vt
  url_identifier = vt.url_id(url)

  The 'url_id' utility function is exposed directly under the top-level 'vt' module.

Quickstart

This quickstart demonstrates how to fetch information about a file using its SHA256 hash. It initializes an asynchronous `vt.Client` with an API key from an environment variable, retrieves a `vt.Object` representing the file, and prints some of its attributes. The client is automatically closed using `async with`.

import os
import asyncio
import vt

async def get_file_info(api_key: str, file_hash: str):
    """Fetches information about a file hash from VirusTotal."""
    async with vt.Client(api_key) as client:
        try:
            file_obj = await client.get_object(f"/files/{file_hash}")
            print(f"File SHA256: {file_obj.sha256}")
            print(f"File Size: {file_obj.size} bytes")
            print(f"Detection Stats: {file_obj.last_analysis_stats}")
        except vt.APIError as e:
            print(f"VirusTotal API error: {e}")
        except Exception as e:
            print(f"An unexpected error occurred: {e}")

if __name__ == "__main__":
    VIRUSTOTAL_API_KEY = os.environ.get('VIRUSTOTAL_API_KEY', '')
    if not VIRUSTOTAL_API_KEY:
        print("Please set the VIRUSTOTAL_API_KEY environment variable.")
    else:
        # Example SHA256 hash of an EICAR test file
        example_hash = "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"
        asyncio.run(get_file_info(VIRUSTOTAL_API_KEY, example_hash))