Install & Compatibility
Where this runs
tested against v0.24.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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 87.3MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 8.3s · import 0.000s · 88MB
96MB installed
● package 96MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Wormhole
✓ from wormhole import create
✗ from magic_wormhole.api import Wormhole
WormholeStatus
✓ from wormhole import WormholeStatus
DilationStatus
✓ from wormhole import DilationStatus
This quickstart demonstrates how to programmatically send data using the `magic-wormhole` API. Run this script, and it will output a wormhole code. On another machine, a recipient would initiate a transfer by calling `Wormhole.from_code(code)` and then `await w.receive_data()` (or `receive_file()`). The API is asynchronous, requiring `async`/`await` and `asyncio.run()`.
import asyncio
from magic_wormhole.api import Wormhole
async def send_data_example():
w = Wormhole()
code = await w.get_code()
print(f"Your wormhole code is: {code}")
print("Waiting for recipient to connect...")
# In a real scenario, you'd wait for connection confirmation before sending sensitive data.
# The 'send_data' or 'send_file' automatically handles the rendezvous.
data_to_send = b"Hello, magic wormhole!"
print(f"Sending: '{data_to_send.decode()}'")
await w.send_data(data_to_send)
print("Data sent.")
# The wormhole object must be closed to release resources and ensure clean exit.
await w.close()
if __name__ == "__main__":
# This runs the asynchronous example using asyncio
asyncio.run(send_data_example())
wormhole --version
Debug
Known issues
gotchaBy default, `magic-wormhole` relies on a public relay server for initial connection bootstrapping. If this server is unreachable due to network issues, firewalls, or outages, connections will fail.fixCheck network connectivity and firewall settings. Ensure DNS resolution for `relay.magic-wormhole.io`. For critical applications, consider deploying and configuring your own private relay server (see `wormhole-relay-server` project) and specify its URL to the `Wormhole` constructor: `Wormhole(relay_url='ws://your.relay.server:4000/v1')`.
affects: All versions using the default relay server.
gotchaProgrammatic use of the `magic-wormhole` API is inherently asynchronous and requires managing an event loop (e.g., `asyncio`). Attempting to call async methods without `await` or outside an `async` context will result in runtime errors.fixEnsure all API calls to `Wormhole` methods (like `get_code()`, `send_data()`, `receive_data()`) are properly `await`-ed within `async` functions, and the top-level execution is managed by `asyncio.run()`.
affects: All versions (since 0.11.0, when the API transitioned to returning Deferreds/Futures).
gotchaWormhole codes are designed for one-time, ephemeral use. While the library might allow it, reusing a generated code for multiple, separate transfers or across long durations is not the intended use and can lead to unexpected behavior or security issues.fixGenerate a new wormhole code for each distinct transfer operation to ensure maximum security and reliability.
affects: All versions.
Upgrade
Version history
0.24.0latest on PyPI · released May 5, 2026
Audit
Dependencies
pynaclrequiredProvides core cryptographic primitives for secure communication.
twistedrequiredAsynchronous networking framework used internally for handling connections.
autobahnrequiredWebSocket client/server implementation used with Twisted for relay communication.