ClamAV Client

Common errors

• ConnectionRefusedError: [Errno 111] Connection refused

  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.
  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.

• clamav_client.exceptions.ClamAVClientError: ClamAV server did not respond within timeout of X.X seconds

  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.
  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.

• AttributeError: 'ClamAVClient' object has no attribute 'scan_file'

  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.
  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)`.

Warnings

• breaking Python 3.8 support was dropped in version 0.7.0. The library now requires Python 3.9 or higher.
  Fix: Upgrade your Python environment to 3.9 or newer, or pin `clamav-client<0.7.0` (not recommended).
• breaking The `ClamAVClient.scan_file` method was renamed to `ClamAVClient.scan_stream` in version 0.6.0 to better reflect its underlying streaming behavior.
  Fix: Replace calls to `client.scan_file(filepath)` with `with open(filepath, 'rb') as f: client.scan_stream(f)`.
• gotcha 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.
  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).
• gotcha 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.
  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.

Install

• pip install clamav-client Install latest version

Imports

• ClamAVClient

  from clamav_client import ClamAVClient

• ClamAVClientError

  from clamav_client.exceptions import ClamAVClientError

  Commonly imported for handling client-specific exceptions.

Quickstart

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.

import os
from clamav_client import ClamAVClient
from clamav_client.exceptions import ClamAVClientError

# Configure ClamAV server details, use environment variables for production
CLAMAV_HOST = os.environ.get('CLAMAV_HOST', '127.0.0.1')
CLAMAV_PORT = int(os.environ.get('CLAMAV_PORT', '3310'))
CLAMAV_TIMEOUT = float(os.environ.get('CLAMAV_TIMEOUT', '10.0'))

client = ClamAVClient(host=CLAMAV_HOST, port=CLAMAV_PORT, timeout=CLAMAV_TIMEOUT)

try:
    # Ping the ClamAV server to check connectivity
    version = client.ping()
    print(f"Connected to ClamAV server (version: {version})")

    # Create a dummy file for scanning
    dummy_file_path = "test_file.txt"
    with open(dummy_file_path, "w") as f:
        f.write("This is a clean test file.")

    # Scan a local file
    print(f"Scanning file: {dummy_file_path}")
    with open(dummy_file_path, "rb") as f:
        scan_result = client.scan_stream(f)

    if scan_result.is_infected:
        print(f"File '{dummy_file_path}' is infected! Virus: {scan_result.virus_name}")
    else:
        print(f"File '{dummy_file_path}' is clean.")

    # Clean up the dummy file
    os.remove(dummy_file_path)

except ClamAVClientError as e:
    print(f"Error communicating with ClamAV server: {e}")
except ConnectionRefusedError:
    print(f"Connection refused. Is ClamAV running at {CLAMAV_HOST}:{CLAMAV_PORT}?")
except Exception as e:
    print(f"An unexpected error occurred: {e}")