Install & Compatibility
Where this runs
tested against v1.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.95 runs
installs and imports cleanly · install 0.0s · import 0.266s · 18.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.228s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
nexusrpc
✓ import nexusrpc
service
✓ from nexusrpc import service
Operation
✓ from nexusrpc import Operation
handler
✓ from nexusrpc import handler
This quickstart demonstrates how to define a Nexus service and implement a synchronous operation handler. It uses dataclasses for input and output types, decorates a class as a Nexus service, and then implements a service handler with a decorated synchronous operation.
from dataclasses import dataclass
import nexusrpc
@dataclass
class MyInput:
name: str
@dataclass
class MyOutput:
message: str
@nexusrpc.service
class MyNexusService:
my_sync_operation: nexusrpc.Operation[MyInput, MyOutput]
@nexusrpc.handler.service_handler(service=MyNexusService)
class MyNexusServiceHandler:
@nexusrpc.handler.sync_operation
async def my_sync_operation(
self, ctx: nexusrpc.handler.StartOperationContext, input: MyInput
) -> MyOutput:
return MyOutput(message=f"Hello {input.name}!")
# In a real application, you would instantiate MyNexusServiceHandler
# and integrate it with your server/worker to process Nexus requests.
# For example:
# handler_instance = MyNexusServiceHandler()
Debug
Known issues
breakingThe nexus-rpc SDK is currently at an experimental release stage. Backwards-incompatible changes are anticipated until a stable release is announced.fixMonitor official releases and changelogs for breaking changes. Pin exact versions in your `requirements.txt` to prevent unexpected updates.
affects: All versions up to 1.4.0
gotchaThe PyPI package name 'nexus-rpc' was previously used by an unrelated project. Ensure you are using the correct SDK for the Nexus synchronous RPC protocol from the `nexus-rpc` GitHub organization.fixVerify the project's origin and documentation (github.com/nexus-rpc/sdk-python) to confirm you are using the intended library.
affects: All versions
gotchaThe SDK for the Nexus RPC protocol only provides components for implementing handlers. It does not include reference implementations for Nexus servers or clients.fixYou will need to implement or integrate a Nexus server and client separately to utilize the defined services and handlers. If integrating with Temporal, refer to their Nexus documentation for server-side setup.
affects: All versions up to 1.4.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'nexusrpc'
The `nexus-rpc` library has not been installed, or there's an issue with the Python environment where it's not accessible.
fixEnsure the library is installed using pip: `pip install nexus-rpc` or `uv add nexus-rpc`.
nexusrpc.HandlerError
This is a custom exception raised by the `nexus-rpc` framework to indicate errors that occur during the handling of a Nexus operation, intended to be reported back to the caller.
fixDevelopers should catch `nexusrpc.HandlerError` in their handler implementations to gracefully manage and report operation failures, optionally specifying a `HandlerErrorType` and message for more context. Example: `raise nexusrpc.HandlerError("Invalid input", type=nexusrpc.HandlerErrorType.BAD_REQUEST)`. AttributeError: 'module' object has no attribute 'service'
This error likely occurs when attempting to define a Nexus service without correctly importing or using the `@nexusrpc.service` decorator. The `service` attribute is expected to be part of the `nexusrpc` module for decorating service classes.
fixEnsure that `nexusrpc` is imported and the service class is correctly decorated with `@nexusrpc.service`, like this: `import nexusrpc` followed by `@nexusrpc.service class MyNexusService: ...`.
AttributeError: 'module' object has no attribute 'handler'
This error occurs when trying to use decorators like `@nexusrpc.handler.service_handler` or `@nexusrpc.handler.sync_operation` without properly accessing the `handler` submodule within `nexusrpc`.
fixMake sure you are explicitly importing or accessing the `handler` submodule for its decorators. For example: `from nexusrpc import handler` or by fully qualifying the name as shown in examples: `@nexusrpc.handler.service_handler(...)`.
Upgrade
Version history
1.4.0latest on PyPI · released Feb 25, 2026
Audit
Dependencies
No dependency data recorded yet.