python-osc

1.10.2 verified Fri May 01 auth: no python

Pure Python implementation of the Open Sound Control (OSC) protocol, providing both UDP and TCP server and client classes. Version 1.10.2 supports Python >=3.10. Released irregularly with focus on robustness and simplicity.

pip install python-osc

Common errors

error ModuleNotFoundError: No module named 'pythonosc' ↓

cause Library not installed

fix

pip install python-osc

error ImportError: cannot import name 'SimpleUDPClient' from 'pythonosc' ↓

cause Incorrect import path; SimpleUDPClient is in submodule

fix

from pythonosc.udp_client import SimpleUDPClient

error TypeError: handler() takes 2 positional arguments but 3 were given ↓

cause Server callback signature changed in v1.8.0; old handler expects (addr, *args) but new one passes (addr, message)

fix

Update handler to accept (addr, osc_message) and access arguments via osc_message.params

error socket.gaierror: [Errno -2] Name or service not known ↓

cause Client was given a hostname that cannot be resolved

fix

Use an IP address string like '127.0.0.1' instead of a hostname

Warnings

breaking In version 1.8.0, the UDP server callback signature changed from (address: str, *osc_args) to (address: str, osc_message: OscMessage). Code using positional args will crash. ↓

fix Update server handlers to accept OscMessage object and access arguments via osc_message.params.

gotcha TCP server and client are available but require explicit import from pythonosc.tcp_server and pythonosc.tcp_client. They have different APIs (e.g., TCP client uses send_message method but may need manual connection). ↓

fix Use UDP unless you need guaranteed delivery. Check examples in the repository for TCP usage.

gotcha The library does not validate OSC compatibility beyond basic packet structure; malformed messages may be silently dropped or raise cryptic errors. ↓

fix Always build messages using the provided classes (OscMessage, OscBundle) rather than constructing raw byte strings.

Imports

SimpleUDPClient
wrong
```
from pythonosc import SimpleUDPClient
```
correct
```
from pythonosc.udp_client import SimpleUDPClient
```
SimpleUDPClient is in the udp_client submodule, not at package root.

SimpleUDPServer

wrong

from pythonosc import SimpleUDPServer

correct

from pythonosc.udp_server import SimpleUDPServer

Similar submodule requirement.

OSCPacket
wrong
```
from pythonosc import OSCPacket
```
correct
```
from pythonosc.osc_packet import OscPacket
```
Class is OscPacket with capital O, and under osc_packet module.

OscMessage

wrong

from pythonosc import OscMessage

correct

from pythonosc.osc_message import OscMessage

Located in osc_message submodule.

Quickstart

Minimal example to send an OSC message over UDP.

from pythonosc.udp_client import SimpleUDPClient

client = SimpleUDPClient("127.0.0.1", 9000)
client.send_message("/hello", [1, 2.0, "world"])
print("Sent OSC message to 127.0.0.1:9000")