# Trio: a friendly Python library for async concurrency and I/O

The Trio project’s goal is to produce a production-quality, permissively licensed, async/await-native I/O library for Python. Like all async libraries, its main purpose is to help you write programs that do multiple things at the same time with parallelized I/O. A web spider that wants to fetch lots of pages in parallel, a web server that needs to juggle lots of downloads and websocket connections at the same time, a process supervisor monitoring multiple subprocesses… that sort of thing. Compared to other libraries, Trio attempts to distinguish itself with an obsessive focus on usability and correctness. Concurrency is complicated; we try to make it easy to get things right.

Trio was built from the ground up to take advantage of the latest Python features, and draws inspiration from many sources, in particular Dave Beazley’s Curio. The resulting design is radically simpler than older competitors like asyncio and Twisted, yet just as capable. Trio is the Python I/O library I always wanted; I find it makes building I/O-oriented programs easier, less error-prone, and just plain more fun. Perhaps you’ll find the same.

This project is young and still somewhat experimental: the overall design is solid and the existing features are fully tested and documented, but you may encounter missing functionality or rough edges. We do encourage you do use it, but you should read and subscribe to issue #1 to get warning and a chance to give feedback about any compatibility-breaking changes.

Vital statistics:

- Supported environments: We test on

  - Python: 3.9+ (CPython and PyPy)

  - Windows, macOS, Linux (glibc and musl), FreeBSD

  Other environments might also work; give it a try and see.

- Install: `python3 -m pip install -U trio` (or on Windows, maybe `py -3 -m pip install -U trio`). No compiler needed.

- Tutorial and reference manual: https://trio.readthedocs.io

- Bug tracker and source code: https://github.com/python-trio/trio

- Real-time chat: https://gitter.im/python-trio/general

- Discussion forum: https://trio.discourse.group

- License: MIT or Apache 2, your choice

- Contributor guide: https://trio.readthedocs.io/en/latest/contributing.html

- Code of conduct: Contributors are requested to follow our code of conduct in all project spaces.

Trio's friendly, yet comprehensive, manual:

- Tutorial
  - Before you begin
  - If you get lost or confused…
  - Async functions
  - A kinder, gentler GIL
  - Networking with Trio
  - When things go wrong: timeouts, cancellation and exceptions in concurrent tasks
- Awesome Trio Libraries
  - Getting Started
  - Web and HTML
  - Database
  - IOT
  - Building Command Line Apps
  - Building GUI Apps
  - Multi-Core/Multiprocessing
  - Stream Processing
  - RPC
  - Testing
  - Tools and Utilities
  - Trio/Asyncio Interoperability
- Trio’s core functionality
  - Entering Trio
  - General principles
  - Time and clocks
  - Cancellation and timeouts
  - Tasks let you do multiple things at once
  - Task-local storage
  - Synchronizing and communicating between tasks
  - Notes on async generators
  - Threads (if you must)
  - Interactive debugging
  - Exceptions and warnings
- I/O in Trio
  - The abstract Stream API
  - Low-level networking with `trio.socket`
  - Asynchronous filesystem I/O
  - Spawning subprocesses
  - Signals
- Testing made easier with `trio.testing`
  - Test harness integration
  - Time and timeouts
  - Inter-task ordering
  - Streams
  - Virtual networking for testing
  - Testing checkpoints
  - ExceptionGroup helpers
- Introspecting and extending Trio with `trio.lowlevel`
  - Debugging and instrumentation
  - Low-level process spawning
  - Low-level I/O primitives
  - Global state: system tasks and run-local variables
  - Trio tokens
  - Spawning threads
  - Safer KeyboardInterrupt handling
  - Sleeping and waking
  - Task API
  - Using “guest mode” to run Trio on top of other event loops
  - Handing off live coroutine objects between coroutine runners
- Design and internals
  - High-level design principles
  - User-level API principles
  - Specific style guidelines
  - A brief tour of Trio’s internals
- Release history
  - Trio 0.29.0 (2025-02-14)
  - Trio 0.28.0 (2024-12-25)
  - Trio 0.27.0 (2024-10-17)
  - Trio 0.26.2 (2024-08-08)
  - Trio 0.26.1 (2024-08-05)
  - Trio 0.26.0 (2024-07-05)
  - Trio 0.25.1 (2024-05-16)
  - Trio 0.25.0 (2024-03-17)
  - Trio 0.24.0 (2024-01-10)
  - Trio 0.23.2 (2023-12-14)
  - Trio 0.23.1 (2023-11-04)
  - Trio 0.23.0 (2023-11-03)
  - Trio 0.22.2 (2023-07-13)
  - Trio 0.22.1 (2023-07-02)
  - Trio 0.22.0 (2022-09-28)
  - Trio 0.21.0 (2022-06-07)
  - Trio 0.20.0 (2022-02-21)
  - Trio 0.19.0 (2021-06-15)
  - Trio 0.18.0 (2021-01-11)
  - Trio 0.17.0 (2020-09-15)
  - Trio 0.16.0 (2020-06-10)
  - Trio 0.15.1 (2020-05-22)
  - Trio 0.15.0 (2020-05-19)
  - Trio 0.14.0 (2020-04-27)
  - Trio 0.13.0 (2019-11-02)
  - Trio 0.12.1 (2019-08-01)
  - Trio 0.12.0 (2019-07-31)
  - Trio 0.11.0 (2019-02-09)
  - Trio 0.10.0 (2019-01-07)
  - Trio 0.9.0 (2018-10-12)
  - Trio 0.8.0 (2018-10-01)
  - Trio 0.7.0 (2018-09-03)
  - Trio 0.6.0 (2018-08-13)
  - Trio 0.5.0 (2018-07-20)
  - Trio 0.4.0 (2018-04-10)
  - Trio 0.3.0 (2017-12-28)
  - Trio 0.2.0 (2017-12-06)
  - Trio 0.1.0 (2017-03-10)
- Contributing to Trio and related projects
  - Getting started
  - Providing support
  - Preparing pull requests
  - Joining the team
  - Managing issues
  - Governance
- Preparing a release
- Code of Conduct
  - When Something Happens
  - Our Pledge
  - Our Standards
  - Scope
  - Maintainer Enforcement Process
  - Enforcement Examples
  - Attribution

# Indices and tables

- Index

- Module Index

- Search Page

- Glossary