# Twisted: a Python event-driven networking engine for protocol work

> Twisted bundles HTTP, DNS, mail, SSH, IRC and XMPP protocol implementations behind one event loop. It is a strong fit when you need a protocol client or server that already exists, and a poor fit when you want a small async HTTP client.

**twisted/twisted** — Event-driven networking engine written in Python.

- Repository: https://github.com/twisted/twisted
- Website: https://twisted.org
- Stars: 5,992 · Forks: 1,224
- Language: Python
- License: NOASSERTION
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/twisted-twisted

## The problem Twisted solves: many protocols, one event loop

Writing a network client usually means picking a protocol library per protocol. An HTTP client here, a DNS resolver there, an SMTP sender somewhere else, each with its own connection handling and its own idea of how to wait on a socket. Twisted's answer is to put the waiting in one place and the protocols on top of it. The README lists the modules that share that base: twisted.web for HTTP clients, servers, HTML templating and a WSGI server; twisted.conch for SSHv2 and Telnet; twisted.words for IRC and XMPP; twisted.mail for IMAPv4, POP3 and SMTP; twisted.names for DNS; twisted.positioning for NMEA GPS receivers; and twisted.trial for tests. That list is the product. If your application needs two or three of those protocols in the same process, Twisted removes the work of reconciling three separate event loops, and it removes the class of bug where one library blocks the thread the others are using. The audience is therefore specific: people building servers, protocol gateways, or clients for protocols that are not HTTP. If you only need to fetch JSON over HTTPS, the module list is mostly irrelevant to you.

## How the reactor and Deferred model fit together

The README states that Twisted supports select on all platforms, poll on most POSIX platforms, epoll on Linux, kqueue on FreeBSD and macOS, IOCP on Windows, and various GUI event loops including GTK+2/3, Qt and wxWidgets. Third-party reactors can plug in and supply additional event loops. That is the architecture in one sentence: the reactor owns the loop, and everything else registers with it. The consequence is that a Twisted program does not call a blocking read and wait; it schedules work and returns. Deferred objects carry the result of that work forward, and twisted.trial exists because testing code written this way needs a runner that understands the reactor rather than a plain unittest invocation. The project's own test suite reflects the coupling between code and loop: the README documents running the suite under a chosen reactor with the TWISTED_REACTOR environment variable, and notes that some tests may fail without the dependencies for a particular subsystem, behind a firewall blocking ports, or when run as root. A framework that owns the loop also owns the process, and that is the trade you accept.

## Installing Twisted and running a first server

The README gives one install command and points to the installation instructions in the documentation for anything beyond it. Package metadata in pyproject.toml sets requires-python to >= 3.10 and lists runtime dependencies including zope.interface >= 8, constantly >= 15.1, incremental >= 24.7.0, automat >= 24.8.1, hyperlink >= 18.0.0, attrs >= 22.2.0 and typing_extensions >= 4.13.2. Those are pulled in automatically.

## A first server

The README does not include a code example, so the honest first step is the documentation site, which the README describes as containing how-tos, code examples and an API reference. For a running service, the pattern to look for there is a site built from a resource tree and handed to the reactor, then reactor.run() at the bottom of the file. The thing to check before writing anything is which reactor you are on. The README shows how the project selects one for its own tests:

## Where Twisted is the wrong tool

The reactor is global. A process has one, it is installed by importing it, and libraries that want to run their own loop inside the same process will fight it. That is the failure mode to plan for, and the README does not document a supported way to run two reactors side by side. There is also a testing cost: the README's own notes say some tests may fail without particular subsystem dependencies, behind a firewall, or when run as root, which tells you the suite touches real sockets and real ports rather than mocking them away. If your CI runs in a locked-down container, expect to spend time on that. The third case is scope. Someone who wants an async HTTP client with a small dependency tree will find that installing Twisted brings in zope.interface, constantly, incremental, automat, hyperlink and attrs alongside it, and the HTTP portion is one module among many. The framework is priced for people who use several of its modules.

## Twisted compared with asyncio and trio

The practical alternative for new Python code is asyncio, which is in the standard library and uses async and await rather than Deferred objects. The difference is not just syntax. asyncio gives you a loop and a set of primitives; it does not ship an IMAP server, an SSH implementation, or a DNS server toolkit. Twisted ships those, and they were written against its own conventions. Trio takes a third position, with structured concurrency as the organising idea rather than a callback-and-Deferred chain, and it is also a smaller surface. Choosing Twisted over asyncio is choosing the protocol modules and the years of edge cases behind them; choosing asyncio is choosing a smaller dependency footprint and a language-level syntax that new contributors already know. Neither is a default. If your work is HTTP-shaped, asyncio plus an HTTP library is the shorter path. If your work is a DNS server or a mail gateway, the modules in this repository are the reason to be here.

## Maintenance, upgrades and the licence question

The repository is not archived, and the last push was on 2026-09-17. The most recent release in the list is twisted-26.4.0 on 2026-05-11, preceded by two release candidates in late April 2026. The versioning is calendar-based, so a major number changes yearly and minor numbers carry the rest. pyproject.toml declares license = "MIT", and the README states that Twisted is an MIT-licensed open source project and that the included LICENSE file describes this in detail. The repository's licence field is reported as NOASSERTION, which means the hosting platform did not classify it automatically; the file in the tree is the authority, not the label. The README also carries an explicit warranty disclaimer stating the software is provided as is without warranty of any kind. On upgrade cost, the README points to NEWS.rst for changes in each release, and the project uses tox environments for its own checks, including tox -e lint for coding standards and tox -e mypy for static typing. Those are the project's internal gates; nothing in the README describes a deprecation policy or a support window for older releases, so a team planning a long-lived deployment should read NEWS.rst rather than assume one.

## Conclusion

Adopt Twisted when you need a protocol implementation that already ships in the tree, such as twisted.names for DNS or twisted.mail for IMAP, POP3 and SMTP, and you can accept the reactor as the centre of your process. Do not adopt it for a small outbound HTTP client, where httpx or aiohttp is a lighter dependency; the README's own example installs Twisted as a whole. Before committing, verify two things on your target Python: that pip install twisted resolves against zope.interface >= 8 and attrs >= 22.2.0, and that the reactor you intend to run, such as epoll on Linux or kqueue on macOS, is the one your test environment selects when you set TWISTED_REACTOR.

## FAQ

### How do I install Twisted?

The README gives a single command, pip install twisted, and points to the installation instructions in the documentation for anything beyond that. The package metadata requires Python 3.10 or newer.

### Which Python versions does Twisted support?

pyproject.toml sets requires-python to >= 3.10 and lists classifiers for Python 3.10 through 3.14.

### What event loops can Twisted run on?

The README lists select on all platforms, poll on most POSIX platforms, epoll on Linux, kqueue on FreeBSD and macOS, IOCP on Windows, and GUI event loops including GTK+2/3, Qt and wxWidgets. Third-party reactors can plug in as well.

## Sources

- [Issues](https://github.com/twisted/twisted/issues)
- [Project website](https://twisted.org)
- [README](https://github.com/twisted/twisted/blob/trunk/README.md)
- [Releases](https://github.com/twisted/twisted/releases)
- [twisted/twisted on GitHub](https://github.com/twisted/twisted)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/twisted-twisted