Install & Compatibility
Where this runs
tested against v6.0.3 · 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.049s · 17.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.8s · import 0.041s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Session
✓ from vici import Session
✗ import vici
EventListener
✓ from vici import EventListener
StopListening
✓ from vici import StopListening
This quickstart demonstrates how to connect to the strongSwan `charon` daemon via its VICI Unix socket, retrieve its version, and list configured connections. It includes error handling for common connection issues like missing sockets or permission errors. Remember to ensure the strongSwan daemon is running and accessible.
import vici
import socket
import os
# Default VICI socket path for Unix-like systems
VICI_SOCKET_PATH = os.environ.get('VICI_SOCKET', '/var/run/charon.vici')
try:
# Connect to the VICI socket
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.connect(VICI_SOCKET_PATH)
session = vici.Session(s)
# Get and print the daemon version information
version_info = session.version()
print(f"Connected to strongSwan daemon: {version_info['daemon']} {version_info['version']} "
f"({version_info['sysname']}, {version_info['release']}, {version_info['machine']})")
# Example: List loaded connections
print("\nLoaded Connections:")
conns_found = False
for conn in session.list_conns():
conns_found = True
print(f" - {list(conn.keys())[0]}") # Connection name is the first key
if not conns_found:
print(" (No connections found)")
# Important: Close the session/socket when done
session.close()
s.close()
except FileNotFoundError:
print(f"Error: VICI socket not found at {VICI_SOCKET_PATH}. Is strongSwan charon running?")
except PermissionError:
print(f"Error: Permission denied when accessing VICI socket at {VICI_SOCKET_PATH}. "
"Adjust socket permissions or run with appropriate privileges.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
gotchaIterators returned by methods like `list_conns()` are Python generators. If not fully consumed (e.g., by iterating through them entirely), they must be explicitly closed using the `.close()` method to release resources.fixEnsure you iterate through all results or call `generator.close()` explicitly if you break out of a loop prematurely.
affects: All versions
gotchaThe VICI protocol for strongSwan can, in some message structures, rely on the order of key-value pairs within a dictionary. The `vici` library returns `OrderedDict` instances for these structures; it's recommended to use `OrderedDict` when constructing messages where order is semantically significant to avoid unexpected behavior.fixWhen constructing VICI messages that require ordered elements, use `collections.OrderedDict` for nested dictionaries instead of standard Python `dict`.
affects: All versions
breakingOlder versions of the `vici` Python client (installed via pip) might encounter compatibility issues or missing direct command wrappers when used with much newer strongSwan `charon` daemon versions or VICI plugin versions. While many issues have been resolved, significant version mismatches can lead to unexpected behavior or missing functionality.fixKeep your `vici` Python library version in sync with your strongSwan `charon` daemon's VICI plugin version. If a direct method like `session.get_algorithms()` is missing, use the more generic `session.request('get-algorithms')` method. affects: Prior to 5.8.0 (client-daemon mismatch)
gotchaConnecting to the default VICI Unix socket (`/var/run/charon.vici`) often requires elevated privileges or specific file permissions. A `PermissionError` indicates the user running the script lacks the necessary access.fixConfigure strongSwan's `vici` plugin to create the socket with more permissive group write access and add your user to that group, or (for testing) temporarily adjust socket permissions (e.g., `sudo chmod 777 /var/run/charon.vici`). Running the script as root is another option but generally not recommended for production.
affects: All versions
Upgrade
Version history
6.0.3latest on PyPI · released Oct 27, 2025
Audit
Dependencies
socketrequiredUsed for establishing communication with the strongSwan VICI socket. This is a built-in Python module.