{"id":7080,"library":"clamav-client","title":"ClamAV Client","description":"The clamav-client library (current version 0.7.2) provides a Python client for interacting with a ClamAV antivirus daemon, allowing applications to scan files and streams for viruses. It is actively maintained, with releases typically tied to feature updates, bug fixes, and Python version support.","status":"active","version":"0.7.2","language":"en","source_language":"en","source_url":"https://github.com/artefactual-labs/clamav-client","tags":["antivirus","clamav","security","file scanning","client","malware"],"install":[{"cmd":"pip install clamav-client","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for underlying HTTP communication with the ClamAV server.","package":"requests","optional":false}],"imports":[{"symbol":"ClamAVClient","correct":"from clamav_client import ClamAVClient"},{"note":"Commonly imported for handling client-specific exceptions.","symbol":"ClamAVClientError","correct":"from clamav_client.exceptions import ClamAVClientError"}],"quickstart":{"code":"import os\nfrom clamav_client import ClamAVClient\nfrom clamav_client.exceptions import ClamAVClientError\n\n# Configure ClamAV server details, use environment variables for production\nCLAMAV_HOST = os.environ.get('CLAMAV_HOST', '127.0.0.1')\nCLAMAV_PORT = int(os.environ.get('CLAMAV_PORT', '3310'))\nCLAMAV_TIMEOUT = float(os.environ.get('CLAMAV_TIMEOUT', '10.0'))\n\nclient = ClamAVClient(host=CLAMAV_HOST, port=CLAMAV_PORT, timeout=CLAMAV_TIMEOUT)\n\ntry:\n    # Ping the ClamAV server to check connectivity\n    version = client.ping()\n    print(f\"Connected to ClamAV server (version: {version})\")\n\n    # Create a dummy file for scanning\n    dummy_file_path = \"test_file.txt\"\n    with open(dummy_file_path, \"w\") as f:\n        f.write(\"This is a clean test file.\")\n\n    # Scan a local file\n    print(f\"Scanning file: {dummy_file_path}\")\n    with open(dummy_file_path, \"rb\") as f:\n        scan_result = client.scan_stream(f)\n\n    if scan_result.is_infected:\n        print(f\"File '{dummy_file_path}' is infected! Virus: {scan_result.virus_name}\")\n    else:\n        print(f\"File '{dummy_file_path}' is clean.\")\n\n    # Clean up the dummy file\n    os.remove(dummy_file_path)\n\nexcept ClamAVClientError as e:\n    print(f\"Error communicating with ClamAV server: {e}\")\nexcept ConnectionRefusedError:\n    print(f\"Connection refused. Is ClamAV running at {CLAMAV_HOST}:{CLAMAV_PORT}?\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `ClamAVClient`, ping the server to verify connectivity, and scan a local file using `scan_stream`. It includes error handling for common connection and client-specific issues."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer, or pin `clamav-client<0.7.0` (not recommended).","message":"Python 3.8 support was dropped in version 0.7.0. The library now requires Python 3.9 or higher.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"Replace calls to `client.scan_file(filepath)` with `with open(filepath, 'rb') as f: client.scan_stream(f)`.","message":"The `ClamAVClient.scan_file` method was renamed to `ClamAVClient.scan_stream` in version 0.6.0 to better reflect its underlying streaming behavior.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Ensure the ClamAV daemon (`clamd`) is running, listening on the correct IP address (e.g., `0.0.0.0` or `127.0.0.1`), and the firewall is not blocking the port (default 3310).","message":"The ClamAV server must be running and accessible at the specified host and port. Connection issues (e.g., 'Connection refused') are common if the server is down or incorrectly configured.","severity":"gotcha","affected_versions":"All"},{"fix":"Increase the `timeout` parameter during `ClamAVClient` initialization (e.g., `ClamAVClient(..., timeout=60.0)`). For very large files, consider splitting them or processing them in chunks if your ClamAV setup supports it, though `scan_stream` is generally efficient for this.","message":"Large files can cause `ClamAVClientError` with a timeout message if the ClamAV server takes too long to respond. The `timeout` parameter in `ClamAVClient` constructor controls the client-side timeout.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify the ClamAV daemon (`clamd`) is running. Check its configuration (`clamd.conf`) for `LocalSocket` or `TCPSocket` settings and ensure the client's host/port match. Also, check firewall rules on both client and server machines.","cause":"The Python client tried to connect to the ClamAV server, but the server was not running, was not listening on the specified host/port, or a firewall blocked the connection.","error":"ConnectionRefusedError: [Errno 111] Connection refused"},{"fix":"Increase the `timeout` parameter when initializing `ClamAVClient` (e.g., `ClamAVClient(host='...', port=..., timeout=30.0)`). Ensure the ClamAV server itself is adequately resourced and not overloaded.","cause":"The ClamAV server took longer than the configured client-side timeout to process the request, often due to scanning a very large file or network latency.","error":"clamav_client.exceptions.ClamAVClientError: ClamAV server did not respond within timeout of X.X seconds"},{"fix":"Migrate your code to use `scan_stream`. Instead of `client.scan_file(filepath)`, use `with open(filepath, 'rb') as f: scan_result = client.scan_stream(f)`.","cause":"You are attempting to use the `scan_file` method, which was deprecated and removed in favor of `scan_stream` in versions 0.6.0 and later.","error":"AttributeError: 'ClamAVClient' object has no attribute 'scan_file'"}]}