Install & Compatibility
Where this runs
tested against v6.0.2 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.118s · 20MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.112s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
rpyc.utils.server.ThreadedServer
✓ from rpyc.utils.server import ThreadedServer
rpyc.Service
✓ import rpyc
class MyService(rpyc.Service):
# ...
Custom services typically inherit from `rpyc.Service`.
rpyc.classic.connect
✓ import rpyc
conn = rpyc.classic.connect('localhost', 18812)
Used for 'classic' RPyC connections to directly access remote modules and built-ins.
This quickstart demonstrates a simple RPyC client-server interaction. First, save the server code as `server.py` and run it in a terminal. Then, save the client code as `client.py` and run it in another terminal to connect to the server, call a remote method, and access a remote module.
# server.py
import rpyc
from rpyc.utils.server import ThreadedServer
class MathService(rpyc.Service):
def on_connect(self, conn):
print("Client connected!")
def on_disconnect(self, conn):
print("Client disconnected!")
def exposed_fib(self, n):
"""Calculates the Fibonacci sequence up to n."""
seq = []
a, b = 0, 1
while a < n:
seq.append(a)
a, b = b, a + b
return seq
if __name__ == '__main__':
# Using a fixed port for demonstration
port = 18812
print(f"Starting MathService on port {port}...")
ts = ThreadedServer(MathService, port=port)
ts.start()
# --- Save the above as server.py and run: python server.py ---
# client.py
import rpyc
import time
def run_client():
host = "localhost" # Replace with your server's address if remote
port = 18812
try:
conn = rpyc.connect(host, port)
print(f"Connected to RPyC server at {host}:{port}")
# Access an exposed method on the root object
result = conn.root.fib(1000)
print(f"Fibonacci sequence up to 1000: {result}")
# Example of accessing a remote module (classic RPyC behavior)
remote_sys_version = conn.modules.sys.version
print(f"Remote Python version: {remote_sys_version.splitlines()[0]}")
conn.close()
print("Connection closed.")
except ConnectionRefusedError:
print(f"Error: Connection refused. Is the server running on {host}:{port}?")
except Exception as e:
print(f"An error occurred: {e}")
if __name__ == '__main__':
# Optional: Give the server a moment to start if run immediately after
# time.sleep(1)
run_client()
Debug
Known issues
breakingRPyC 6.0.0 introduced a security fix for a Remote Code Execution (RCE) vulnerability related to the `__array__` attribute, which breaks backward compatibility for code relying on `numpy`'s usage of this attribute. The RCE was exploitable if the server-side explicitly called `np.array(x)` on a remote object.fixUpgrade to RPyC 6.0.0 or later. If relying on `__array__` for NumPy integration, review usage patterns and potentially adapt to new serialization or exposure methods.
affects: >=4.x.x, fixed in 6.0.0
breakingRPyC 5.0.0 officially dropped support for Python 2, coinciding with its end-of-life. Attempting to connect Python 2 clients to Python 3 servers (or vice-versa) or using RPyC 5+ on Python 2 will lead to incompatibility issues due to fundamental differences in Python's object model and bytecode.fixMigrate all RPyC clients and servers to Python 3.8+ and RPyC 5.0.0 or later.
affects: <5.0.0 (for Python 2 support)
gotchaTeleporting functions (e.g., using `rpyc.utils.classic.teleport_function`) between different Python major versions or even different RPyC versions is not officially supported and can lead to errors due to Python bytecode differences. It is recommended to ensure both client and server run the same Python and RPyC versions when using this feature.fixEnsure client and server use the same Python version and RPyC library version when teleporting functions. For complex objects or closures, consider alternatives like external serialization libraries (e.g., `dill`) or refactoring.
affects: All versions
gotchaRunning a classic RPyC server with `--host 0.0.0.0` (which was the default in older versions) exposes it to arbitrary code execution from any connecting client. This can be a significant security risk.fixBind the RPyC server to a specific IP address (e.g., `127.0.0.1` for local connections or a specific network interface) or use proper authentication and encryption (SSL/TLS, SSH) for production environments. Always review the exposed services and methods carefully.
affects: All versions, especially older defaults
breakingRPyC 5.3.1 included a fix for an experimental thread binding struct that, while fixing issues on some platforms, was not backward compatible. This primarily affects users experimenting with the thread binding feature.fixUpgrade to RPyC 5.3.1 or later. If you were using the experimental thread binding feature on older versions, be aware of potential changes in behavior.
affects: <5.3.1 (for experimental thread binding)
Errors
Common errors & fixes
ConnectionRefusedError: [Errno 111] Connection refused
The RPyC server is not running, is running on a different address/port, or a firewall is blocking the connection.
fixEnsure the RPyC server is started and listening on the specified host and port, and check network configurations or firewalls.
EOFError: stream has been closed
The remote RPyC connection was unexpectedly closed by the server, or the server crashed/shut down while the client was still trying to communicate.
fixVerify the server's stability and ensure it's running. Implement robust error handling and reconnection logic in the client.
rpyc.core.protocol.AuthenticationError: authentication failed
The client or server provided incorrect authentication credentials (e.g., a wrong password or key), or a mismatch in expected authentication methods.
fixEnsure both the RPyC client and server are configured with the correct and matching authentication credentials or settings.
TypeError: cannot pickle <object type 'some_object'> object
You are attempting to pass an object across the RPyC connection that Python's `pickle` module cannot serialize, often due to internal C-level objects or complex state.
fixInstead of sending the unpickleable object directly, extract and send only the necessary serializable data, or use RPyC's exposed services to interact with the object remotely without passing it.
Upgrade
Version history
6.0.2latest on PyPI · released Apr 18, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.8 or higher.