Install & Compatibility
Where this runs
tested against v0.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.010s · 19.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.4s · import 0.011s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ClamdAgnostic
✓ from pyclamd import ClamdAgnostic
✗ from pyclamd import Clamd
ClamdAgnostic is the recommended entry point as it attempts both Unix and network socket connections. 'Clamd' is not directly instantiable.
ClamdNetworkSocket
✓ from pyclamd import ClamdNetworkSocket
ClamdUnixSocket
✓ from pyclamd import ClamdUnixSocket
This quickstart demonstrates how to connect to the ClamAV daemon using `ClamdAgnostic`, ping it to verify connectivity, and then scan both a byte stream and a temporary file containing the EICAR test string. It includes basic error handling for common connection issues.
import pyclamd
import os
# Ensure Clamd daemon is running and accessible (e.g., via network or Unix socket)
# For network socket: Host (default '127.0.0.1'), Port (default 3310)
# For Unix socket: Socket path (default '/var/run/clamav/clamd.ctl')
clamd_host = os.environ.get('CLAMD_HOST', '127.0.0.1')
clamd_port = int(os.environ.get('CLAMD_PORT', '3310'))
clamd_socket = os.environ.get('CLAMD_SOCKET', '/var/run/clamav/clamd.ctl') # Default for many Linux systems
try:
# Use ClamdAgnostic for automatic detection (Unix socket preferred if available)
# This will try UnixSocket first, then NetworkSocket
cd = pyclamd.ClamdAgnostic(
unix_socket=clamd_socket,
host=clamd_host,
port=clamd_port
)
# Ping the ClamAV daemon to check connectivity
cd.ping()
print("Successfully connected to ClamAV daemon.")
# EICAR test string (standard antivirus test file)
eicar_string = b"X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*"
# Scan a stream of bytes
result_stream = cd.scan_stream(eicar_string)
print(f"Scan stream result for EICAR: {result_stream}")
# Create a dummy file for file scan
test_file_path = "eicar_test.txt"
with open(test_file_path, "wb") as f:
f.write(eicar_string)
result_file = cd.scan_file(test_file_path)
print(f"Scan file result for '{test_file_path}': {result_file}")
if os.path.exists(test_file_path):
os.remove(test_file_path)
except pyclamd.ClamdError as e:
print(f"ClamAV daemon error: {e}")
print("Please ensure the ClamAV daemon (clamd) is running and accessible.")
print(f" Network: {clamd_host}:{clamd_port}")
print(f" Unix Socket: {clamd_socket}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Errors
Common errors & fixes
pyclamd.ClamdError: Could not connect to ClamAV daemon: [Errno 111] Connection refused
The ClamAV daemon (clamd) is either not running or not listening on the specified network host and port.
fixStart the `clamd` service. Verify the daemon's configuration (`clamd.conf`) for `LocalSocket` or `TCPSocket` settings, and ensure the `pyclamd` client uses matching `host` and `port`.
pyclamd.ClamdError: Could not connect to ClamAV daemon: [Errno 2] No such file or directory
The specified Unix socket path for `clamd` does not exist or is incorrect.
fixCheck the `clamd.conf` for the `LocalSocket` path. Ensure `pyclamd` is configured with the correct `unix_socket` argument (e.g., `ClamdUnixSocket(unix_socket='/var/run/clamav/clamd.ctl')`).
pyclamd.ClamdError: Could not connect to ClamAV daemon: [Errno 13] Permission denied
The user running the Python script does not have sufficient permissions to access the ClamAV daemon's Unix socket file.
fixGrant read/write permissions for the socket file to the user running the script, or run the script as a user (e.g., `clamav`) that already has access. This often involves checking the permissions of `/var/run/clamav/clamd.ctl` and its parent directory.
Upgrade
Version history
0.4.0latest on PyPI · released Aug 27, 2017
Audit
Dependencies
No dependency data recorded yet.