Trio: a Python async library built around structured concurrency

What Trio is for, and who it is actually aimed at

The README frames the goal narrowly: help you write programs that do multiple things at the same time with parallelized I/O. Its own examples are a web spider fetching many pages at once, a web server juggling downloads and websocket connections, and a process supervisor watching several subprocesses. All three are I/O-bound fan-out problems, and that is the shape Trio is designed for.

The intended reader is a Python developer writing new concurrent code, not someone retrofitting an existing application. The project says it draws inspiration from Dave Beazley's Curio and describes its design as simpler than older competitors like asyncio and Twisted while claiming to be just as capable. Trio also states that no prior async experience is required for its tutorial, which tells you the audience includes people who have never written an async function before.

One detail is worth flagging early. The pyproject.toml still carries the classifier Development Status :: 4 - Beta, while the README describes the project as mature and well-tested with features widely used in production. Those two statements come from the same repository and they pull in different directions. Treat the classifier as the more conservative signal and the README as the project's own position.

Trio is not a web framework, an HTTP client, or an application server. It is the concurrency and I/O layer those things would be built on, and the README points readers toward a separate ecosystem of Trio-using libraries rather than bundling one.

Nurseries: how structured concurrency changes the control flow

The central mechanism is the nursery. Where other async libraries let you schedule a coroutine and forget about it, Trio requires spawned tasks to live inside a scope that cannot exit until every task inside it has finished. The README calls this "structured concurrency" and links to an essay titled Notes on structured concurrency, or: Go statement considered harmful as the theoretical introduction.

The practical consequence is that a nursery block has a defined entry and exit. If you open a nursery and start three tasks, control does not leave that block until all three are done. There is no window where a task is still running after the code that created it has moved on, which is the failure mode that makes fire-and-forget task spawning hard to debug.

This is also where the project's stated priorities show up. The README says Trio distinguishes itself with an obsessive focus on usability and correctness, and that concurrency is complicated but the goal is to make it easy to get things right. The nursery is the concrete implementation of that claim: correctness is enforced by the shape of the API rather than by documentation telling you to be careful.

The trade-off is real. Code that genuinely wants a long-lived background task detached from any caller does not map cleanly onto a nursery, because the nursery will wait for it. Trio's answer is that such tasks should be owned by something with a lifetime, but that is a design constraint you have to accept, not a bug you can work around with a flag.

Trio's dependencies are listed in pyproject.toml as attrs, sortedcontainers, idna, outcome, sniffio, plus cffi on Windows for non-PyPy interpreters. The README notes that all dependencies are pure Python except CFFI on Windows, which ships wheels, so no C compiler is needed.

Installing Trio and running a first nursery

Trio installs from PyPI. The README also links a conda-forge badge, so both package indexes are supported. The only runtime requirement stated is Python 3.10 or better, on CPython or a currently maintained PyPy3, running on Linux, macOS, Windows or FreeBSD. The README itself does not print an install command, so the place to start is the PyPI page it links, and the tutorial it links for a first program.

The tutorial's first code is a concurrency example that opens a nursery and starts tasks inside it. That is the example to read before anything else, because the nursery is the piece of the API that has no equivalent in the other async libraries a reader is likely to know.

For I/O rather than pure concurrency, the README points at an echo client and an echo server in the same tutorial. Those two are the shortest path from a toy nursery to something that talks over a network, and they are the examples to read next once the concurrency example makes sense.

If something does not work, the README lists a Gitter chat room, a Discourse forum, GitHub issues and a StackOverflow tag as support channels. The tutorial is the first stop, and the project states it requires no prior async experience.

Where Trio is the wrong choice

The clearest limitation is ecosystem gravity. Trio runs its own event loop, and the README's own framing puts it in contrast with asyncio rather than alongside it. A library written against asyncio primitives will not run on a Trio loop, so adopting Trio means either finding Trio-native equivalents for everything you depend on or giving those dependencies up. For a project whose stack is already asyncio-shaped, that cost usually outweighs the design benefits.

The second limitation is API stability, stated by the project itself. The README says the overall design is solid and breaking changes are rare, but it also says minor interface adjustments occasionally happen and directs anyone who relies on long-term API stability to subscribe to issue #1 for advance notice of compatibility updates. That is an honest disclosure and it should be read as one: Trio does not promise a frozen API.

The Beta classifier in pyproject.toml is a third signal. Whatever the README says about production use, the packaging metadata still labels the release as beta, and downstream tooling that reads classifiers will report it that way.

Finally, Trio is not a general answer to CPU-bound work. The README scopes it to parallelized I/O, and its examples are all network or subprocess fan-out. If your bottleneck is computation, Trio's loop does not remove the GIL problem, and the library does not claim to.

Trio versus asyncio: the difference is in the API contract

The README names asyncio and Twisted as the older competitors Trio is designed to be simpler than, and it names Curio as the specific inspiration. The meaningful comparison is with asyncio, because that is the one in the standard library.

The difference is not performance, and the README makes no performance claim. It is what the API lets you express. asyncio gives you tasks you can create and drop, with cancellation and cleanup left to the programmer. Trio gives you a nursery, where the scope owns the tasks and cancellation propagates through the tree. The README's PyCon 2018 talk link describes implementing the Happy Eyeballs algorithm in an older library versus Trio, which is the project's own illustration of where the two approaches diverge in practice.

Curio is the closer relative. Trio's README describes the design as drawing inspiration from Curio in particular, so the two share the structured-concurrency lineage; Trio is the one with the larger documented ecosystem and the tutorial aimed at newcomers.

Twisted is a different era of the same problem. It predates async/await syntax entirely, so the comparison is between a callback-and-deferred model and a coroutine model, not between two coroutine libraries. The README's claim that Trio is radically simpler than Twisted is a statement about surface area, and it is consistent with the fact that Trio requires Python 3.10 or better while Twisted supports much older interpreters.

The honest summary: if you are starting fresh and can pick your dependencies, Trio's nursery model is easier to reason about than task handles you must track yourself. If you are joining an existing asyncio codebase, the migration cost is the whole argument, and the README offers no migration path.

Maintenance, releases and what the licence actually says

The repository is not archived, and the last push was on 2026-09-21. Recent releases are v0.34.0 on 2026-08-11, v0.33.0 on 2026-02-14 and v0.32.0 on 2025-10-31. That cadence, roughly two releases a year with a patch line in between, is the number to plan around rather than any claim about how actively developed the project is.

The upgrade cost is bounded by the project's own statement that breaking changes are rare but minor interface adjustments do occur. The README's suggested mitigation is to subscribe to issue #1 for advance notice, which is a low-effort way to hear about compatibility changes before you hit them. There is no documented deprecation policy beyond that issue.

On licensing, the README is explicit: Trio is permissively licensed under your choice of MIT or Apache 2. The repository layout confirms this, with LICENSE, LICENSE.MIT and LICENSE.APACHE2 at the top level, and pyproject.toml declaring license = "MIT OR Apache-2.0" with license-files = ["LICENSE*"]. The dual-licence structure means a downstream project can pick whichever of the two fits its own policy. This is a description of what the files say, not legal advice; if the choice matters to your organisation, the LICENSE files are the ones to read.

The build backend is setuptools with a minimum of version 77, and the package is typed, per the Typing :: Typed classifier. The tests live in tests/, with a tox.ini and a ci.sh at the top level, and the project uses newsfragments/ for changelog entries.

Editorial conclusion

Adopt Trio for new concurrent I/O code where you control the event loop, and skip it if your stack is already built on asyncio or Twisted, since the two worlds do not share a loop. Before committing, read the tutorial's echo client and echo server examples, confirm you can run Python 3.10 or better on Linux, macOS, Windows or FreeBSD, and check that every library you depend on has a Trio backend rather than an asyncio-only one.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. python-trio/trio on GitHub
4. README
5. Releases