Install & Compatibility
Where this runs
tested against v26.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.606s · 52.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.5s · import 0.612s · 53MB
54MB installed
● package 54MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
reactor
✓ from twisted.internet import reactor
The core event loop object.
protocol
✓ from twisted.internet import protocol
Base classes for implementing network protocols.
defer
✓ from twisted.internet import defer
Module for Deferred objects and inlineCallbacks.
server
✓ from twisted.web import server, resource
Common imports for building web applications.
This quickstart demonstrates a simple echo server using Twisted's core `reactor` and `protocol` abstractions. It listens on port 8000 and sends back any data received.
from twisted.internet import reactor, protocol
class Echo(protocol.Protocol):
"""As soon as any data is received, send it back."""
def dataReceived(self, data):
self.transport.write(data)
class EchoFactory(protocol.Factory):
def buildProtocol(self, addr):
return Echo()
if __name__ == '__main__':
# This will run the protocol on port 8000
reactor.listenTCP(8000, EchoFactory())
print("Echo server started on port 8000. Press Ctrl+C to stop.")
reactor.run()
twistd --version
Debug
Known issues
breakingThe methods `deferSetUp`, `deferTestMethod`, `deferTearDown`, and `deferRunCleanups` on `twisted.trial.unittest.TestCase` have been removed.fixMigrate away from these deprecated methods. Twisted's `trial` testing framework encourages standard async/await or direct Deferred usage for setup/teardown.
affects: 25.5.0 and later
gotchaAny blocking call (e.g., `time.sleep()`, synchronous I/O, long-running computations) will halt the entire Twisted reactor and block all other active connections and operations.fixAlways use Twisted's asynchronous primitives (e.g., `reactor.callLater`, `defer.Deferred`, `inlineCallbacks`, `twisted.internet.threads.deferToThread`) for operations that might block. Offload CPU-bound tasks to separate threads or processes.
affects: All versions
gotchaThe `twisted.python.failure.Failure` object, which encapsulates tracebacks for error handling, no longer records the exact point of its creation for performance reasons.fixIf you relied on the exact creation traceback for debugging, be aware this information is no longer available. Focus on the traceback within the `Failure` object itself, which points to where the error occurred, rather than where the `Failure` object was instantiated.
affects: 24.10.0 and later
gotchaUnderstanding and correctly chaining `defer.Deferred` objects, especially handling errors (errbacks), can be complex. Unhandled errors in a Deferred chain can silently disappear or lead to unexpected behavior.fixAlways attach an errback to the end of a Deferred chain to catch and log unhandled errors, or ensure that all possible error paths are explicitly handled. Use `inlineCallbacks` or Python's `async/await` syntax (when yielding coroutines, supported from 24.7.0) to simplify Deferred management.
affects: All versions
Errors
Common errors & fixes
RuntimeError: Reactor already running
The Twisted reactor (responsible for the event loop) was attempted to be started again using `reactor.run()` while it was already active.
fixEnsure `reactor.run()` is called only once per application lifecycle. For scheduling tasks after the reactor starts, use `reactor.callWhenRunning(my_function)`.
Unhandled error in Deferred:
A `Deferred` object encountered an exception during its callback chain, but no `errback` was attached to handle the failure, causing it to be logged as unhandled.
fixAdd an `addErrback` callback to your Deferred chain to catch and process exceptions, for example: `d.addErrback(lambda failure: print(f"Error: {failure.getErrorMessage()}"))`. twisted.internet.error.ConnectionRefusedError: Connection refused
A client attempted to connect to a server at a specific host and port, but the connection was actively refused because the server was not running, was unreachable, or a firewall blocked the connection.
fixVerify that the target server application is running and listening on the correct host and port, and check network connectivity and firewall rules.
AttributeError: module 'twisted' has no attribute 'reactor'
The Twisted reactor was attempted to be accessed directly via `twisted.reactor`, but the `reactor` object resides within the `twisted.internet` submodule.
fixImport the reactor specifically from the `twisted.internet` module: `from twisted.internet import reactor`.
twisted.internet.error.TimeoutError: User timeout caused connection failure.
A network operation (e.g., connection attempt or data transfer) exceeded the configured timeout period before it could complete.
fixIncrease the timeout value for the operation if it is expected to take longer, or investigate network latency and performance issues.
Upgrade
Version history
26.4.0latest on PyPI · released May 11, 2026
Audit
Dependencies
zope.interfacerequiredCore dependency for interface definition and implementation.
pyopenssloptionalRequired for TLS/SSL support, especially for clients and servers.
service_identityoptionalUsed for verifying server certificates in TLS connections.
cryptographyoptionalUnderpins TLS/SSL and other cryptographic features.