Open vSwitch Python library

3.7.1 verified Fri May 01 auth: no python

Official Python bindings for Open vSwitch (OVS), version 3.7.1. Provides APIs for interacting with OVS daemons via JSON-RPC, managing OpenFlow, and configuring virtual switches. Released quarterly, used primarily in SDN/NFV environments.

pip install ovs

Common errors

error AttributeError: module 'ovs' has no attribute 'appctl' ↓

cause The appctl module was deprecated and removed in ovs 3.0.

fix

Use 'from ovs import unixctl' instead.

error ImportError: cannot import name 'ovsdb' from 'ovs' (unknown location) ↓

cause The ovsdb module is not always included in pip packages; it is part of the full OVS source distribution.

fix

Install OVS from source or use 'from ovs import db' for lower-level OVSDB access.

error OSError: [Errno 2] No such file or directory: '/var/run/openvswitch/db.sock' ↓

cause The OVS daemon (ovsdb-server) is not running or the socket path is wrong.

fix

Start ovsdb-server: 'sudo service openvswitch-switch start'. Then check socket location with 'ovsdb-tool show-log'.

error AttributeError: 'NoneType' object has no attribute 'recv_block' ↓

cause Stream.open_block() returned an error, and rpc is None.

fix

Check the connection parameters. Use 'tcp:127.0.0.1:6640' or 'unix:/var/run/openvswitch/db.sock'.

Warnings

gotcha The ovs library is not a high-level Python SDK. It is a thin wrapper around OVS internal C libraries. Many functions require deep understanding of OVS internals. Do not expect a user-friendly API. ↓

fix For simpler OVS interactions, consider using ovsdb-client (command-line) or a third-party library like python-ovs.

deprecated The ovs.appctl and ovs.daemon modules are deprecated and may be removed in future versions. Use ovs.unixctl instead. ↓

fix Replace 'from ovs import appctl' with 'from ovs import unixctl'.

breaking Python 2 support removed in ovs 3.0. If you are on Python 2, you must use ovs 2.x. ↓

fix Upgrade to Python 3.6+ and use ovs>=3.0.

gotcha The ovs library uses a custom event loop (poll_loop). Mixing with other event loops (e.g., asyncio, gevent) requires careful integration. Do not assume thread safety. ↓

fix Use ovs event loop exclusively or offload OVS operations to a separate process.

gotcha All OVS library functions expecting a 'bridge' name or 'port' name assume the exact OVS internal naming. Renaming a bridge via the library after creation is not supported. ↓

fix Use the OVS command-line tools for management operations like bridge renaming.

Install

pip install ovs==3.7.1

Imports

vlog
```
from ovs import vlog
```
vlog is a top-level module for logging
jsonrpc
```
from ovs import jsonrpc
```
JSON-RPC utilities
db
```
from ovs import db
```
Database access (OVSDB)
ovsdb
```
from ovs import ovsdb
```
High-level OVSDB client
flow
```
from ovs import flow
```
Flow table utilities
poll_loop
```
from ovs import poll_loop
```
Event loop
posix
```
from ovs import posix
```
POSIX socket helpers
poller
```
from ovs import poller
```
Polling utilities
process
```
from ovs import process
```
Process management
sFlow
```
from ovs import sFlow
```
sFlow remote configuration
stream
```
from ovs import stream
```
Stream abstraction (TCP/SSL/Unix)
timeval
```
from ovs import timeval
```
Time utilities
unixctl
```
from ovs import unixctl
```
Unix control socket
util
```
from ovs import util
```
Miscellaneous utilities
version
```
from ovs import version
```
Version info

Quickstart

Minimal example connecting to OVSDB via JSON-RPC and sending an echo request.

from ovs import vlog
from ovs import jsonrpc
from ovs import stream
import ovs.unixctl
import sys

# Example: connect to a remote OVSDB server via JSON-RPC
if __name__ == '__main__':
    # Initialize logging
    vlog.init()

    # Create a stream to OVSDB (passing connection string)
    # For SSL: ssl:127.0.0.1:6632
    # For TCP: tcp:127.0.0.1:6640
    # For Unix: unix:/var/run/openvswitch/db.sock
    remote = 'tcp:127.0.0.1:6640'
    new_stream, error = stream.Stream.open_block(
        stream.Stream.open(remote))
    if error:
        sys.stderr.write('Failed to connect: %s\n' % error)
        sys.exit(1)

    rpc = jsonrpc.Connection(new_stream)
    # Send a JSON-RPC echo request
    request = jsonrpc.Message.create_request('echo', [])
    rpc.send(request)
    reply, error = rpc.recv_block()
    if error:
        sys.stderr.write('Error: %s\n' % error)
    else:
        print('Reply: %s' % reply)
    rpc.close()