Pre-release

This release is a pre-release and may not be stable for production use.

mt_asyncio

mt_asyncio is a parallel asyncio runtime for free-threaded Python: one event loop that steps asyncio tasks across many OS threads, written in Rust on top of the mio crate.

import mt_asyncio.asyncio as asyncio

async def handle(n):
    await asyncio.sleep(0.1)
    return n * 2

async def main():
    return await asyncio.gather(*[handle(i) for i in range(1000)])

asyncio.run(main())

That is the whole idea: import mt_asyncio.asyncio as asyncio and your existing coroutines run on more than one core.

Experiment: this is an experiment in whether asyncio can be made genuinely parallel on free-threaded Python — not production software. Releases are alpha and the APIs are subject to breaking changes.

Attribution: mt_asyncio is derived from TonIO by Giovanni Barillari and keeps its Rust runtime core; TonIO's own yield- and async-flavoured APIs are not exposed here. mt_asyncio is not affiliated with or endorsed by the TonIO project. See NOTICE.

Note: free-threaded Python (3.14t+) and Unix systems only.

Why

CPython's asyncio loop is single-threaded by design: one thread steps every task, so an async workload cannot use more than one core no matter how many tasks it has. On free-threaded Python that limit is no longer necessary.

mt_asyncio keeps asyncio's API and semantics but replaces the scheduler: tasks are handed to a Rust work-stealing runtime and stepped in parallel on its worker threads. I/O readiness comes from an edge-triggered mio reactor, and run_in_executor from a native blocking thread-pool.

The trade-off is stated up front, because it is the one thing that changes: callbacks are no longer serialized. Stdlib asyncio gives you implicit mutual exclusion (everything runs on the loop thread); mt_asyncio does not. Shared state touched from tasks or callbacks needs a lock — the ones in mt_asyncio.asyncio are genuinely cross-thread. This is the price of using multiple cores.

Install

pip install --pre mt-asyncio

Releases are alpha for now, so --pre is required until the first stable one.

Requires a free-threaded CPython build (python3.14t or python3.15t).

Usage

Everything lives in mt_asyncio.asyncio, which mirrors the asyncio namespace:

import mt_asyncio.asyncio as asyncio

async def worker(queue):
    while True:
        item = await queue.get()
        if item is None:
            return
        await process(item)

async def main():
    queue = asyncio.Queue(maxsize=100)

    async with asyncio.TaskGroup() as tg:
        for _ in range(8):
            tg.create_task(worker(queue))

        async for item in source():
            await queue.put(item)
        for _ in range(8):
            await queue.put(None)

asyncio.run(main())

Supported: run, create_task, gather, wait, wait_for, shield, as_completed, sleep, to_thread, TaskGroup, timeout/timeout_at, Future, Task (with cancel/cancelling/uncancel), Lock, Event, Condition, Semaphore, BoundedSemaphore, Queue/LifoQueue/PriorityQueue, run_coroutine_threadsafe, wrap_future, and the loop's call_soon, call_later, call_at, run_in_executor, getaddrinfo, and sock_* methods.

Networking: add_reader/add_writer, create_connection, create_server, start_tls, open_connection/start_server and TLS.

Not implemented: datagram endpoints, subprocesses, Barrier, and loop policies. See mt_asyncio/asyncio/COMPATIBILITY.md for the full surface, the behavioural differences, and the workarounds.

Third-party libraries

There are two ways to reach a database here, and which one fits depends on the shape of your concurrency rather than on what is supported.

Async driver. psycopg's async API works under compat.install() — it waits on add_reader/add_writer, which are implemented. Its wait_async loop is covered in tests/test_netlibs.py against both backends, and concurrent queries across many connections are verified against a real server.

import mt_asyncio.asyncio as asyncio

asyncio.compat.install()   # before importing psycopg

import psycopg

async def fetch_user(conn, user_id):
    async with conn.cursor() as cur:
        await cur.execute('select name from users where id = %s', (user_id,))
        return await cur.fetchone()

async def main():
    async with await psycopg.AsyncConnection.connect('postgresql:///app') as conn:
        return await fetch_user(conn, 1)

asyncio.run(main())

No thread per query, so concurrency is bounded only by your connection pool. The cost is a reactor hop per round trip.

Sync driver behind to_thread. One pool thread per in-flight query, capped by blocking_threadpool_size (128 by default), and no event-loop work in the query path at all. This is also the only option for clients with no async API — requests, boto3, and plenty of vendor SDKs.

import mt_asyncio.asyncio as asyncio
from psycopg_pool import ConnectionPool

pool = ConnectionPool('postgresql:///app', min_size=16, max_size=16)

async def fetch_user(user_id):
    def query():
        with pool.connection() as conn:
            return conn.execute('select name from users where id = %s', (user_id,)).fetchone()

    return await asyncio.to_thread(query)

async def main():
    return await asyncio.gather(*[fetch_user(i) for i in range(1000)])

asyncio.run(main())

to_thread hands query to the runtime's native blocking pool. Note this is a better to_thread than the stdlib one rather than a fallback from it: on a free-threaded build those threads run Python concurrently, so the queries are genuinely in flight at once instead of taking turns under the GIL — and the coroutines awaiting them are stepped in parallel too. Size the connection pool, or bound it with a Semaphore, so you do not queue more work than the database can take.

The db_query benchmark measures the to_thread pattern; point MT_ASYNCIO_BENCH_DSN at a real server to run it against Postgres.

Blocking calls

Blocking directly in a coroutine is survivable here, which it is not under stdlib: it occupies one worker, and the others keep stepping tasks.

async def handler():
    time.sleep(0.05)      # occupies a worker for 50ms, not the whole loop
    return 'done'

There are two ways to make that safe, and on a free-threaded build both are legitimate — the choice is about failure modes, not speed.

Offload it. await asyncio.to_thread(...) moves the call to the blocking pool and keeps every worker free.

Or just have more workers. Blocked threads are off-CPU, so raising threads costs little. Measured with 64 concurrent 10ms blocking calls:

	8 workers	128 workers
blocking inline	102.6 ms	16.7 ms
via `to_thread`	14.9 ms	18.5 ms
CPU-bound workload	724.8 ms	362.4 ms

At 128 workers, inline blocking matches to_thread, and CPU work did not suffer from oversubscription on an 18-core machine.

What the split still buys is isolation and elasticity, not throughput:

Exhaust the blocking pool and offloads simply queue — the scheduler keeps running. Exhaust the workers and the runtime stalls, because workers are also what run task steps, timers and I/O dispatch. Raising threads moves that cliff without removing it.
Pool threads are created on demand and retire after blocking_threadpool_idle_ttl; workers are created at startup and live for the life of the process.

The cost of the split is that the two pools cannot help each other: a blocking pool thread never steps a coroutine, and a worker never picks up offloaded work.

The cliff is worth seeing, because it is silent. With 4 workers, a 50ms blocking call, and an unrelated task watching how long it is kept off the CPU:

concurrent blockers	throughput	worst stall elsewhere
3 (`threads - 1`)	unaffected	1 ms
4 (`threads`)	still unaffected	51 ms

At exactly the worker count the wall clock looks fine while everything else freezes for the full duration. The default threads is cpu_count() + 4 for this reason — headroom so ordinary blocking does not reach the edge. Use to_thread when you want that guarantee rather than a margin, and raise threads when your workload is mostly blocking and you would rather not partition your threads at all.

Sizing the runtime

run() takes a threads argument, and mt_asyncio.runtime() configures the process-wide runtime up front:

import mt_asyncio
import mt_asyncio.asyncio as asyncio

# 8 worker threads, a smaller blocking pool
mt_asyncio.runtime(threads=8, blocking_threadpool_size=32, context=True)

asyncio.run(main())

option	description	default
`threads`	runtime worker threads (scheduler and execution)	# of CPU cores + 4
`context`	propagate `contextvars` into coroutines (required by the loop)	`False`
`blocking_threadpool_size`	maximum blocking threads	128
`blocking_threadpool_idle_ttl`	idle timeout for blocking threads (seconds)	30
`signals`	signals the runtime listens for

The drop-in boundary

import mt_asyncio.asyncio as asyncio parallelizes code that uses those names. A third-party library does import asyncio internally and gets CPython's.

The C Future/Task are not the obstacle — on 3.14t the current-task slot lives in thread state and Future is internally locked. The problem is the pure-Python layer above them, which has no synchronisation at all: gather._done_callback does an unsynchronised nfinished += 1, so one lost increment means the outer future never resolves, and Lock.acquire check-then-sets _locked over a bare deque. Those failures are hangs, not wrong answers.

Compat mode points those names at mt_asyncio's own locked implementations:

import mt_asyncio.asyncio as asyncio

asyncio.compat.install()   # before importing libraries that should see it

import some_library
asyncio.run(some_library.main())

gather, wait_for, TaskGroup, Lock, Event, Queue, Future, create_task and the rest are redirected, in asyncio and in the submodules that re-export them. Install before importing anything that should see it — shadowing only rebinds module attributes, so a module that already did from asyncio import Lock keeps the original. Patching is process-global; compat.uninstall() reverses it.

Transports are implemented — add_reader/add_writer, create_connection, create_server, start_tls and streams all work, over TLS as well as plain TCP. psycopg's async API, aiohttp and websockets all drive them correctly.

The remaining boundary is one level up, and no lock can close it: a library that shares mutable state between tasks can race, because tasks step in parallel. Both aiohttp and websockets keep a registry of live connections and iterate it during server shutdown while another task mutates it, so their shutdown paths are unreliable here even though serving traffic is not. anyio (and therefore httpx) livelocks against our cooperative cancellation and is unsupported. See COMPATIBILITY.md for the measurements.

Compatibility testing

tests/test_parity.py is a differential suite: every scenario is written once and run against both stdlib asyncio and mt_asyncio.asyncio, asserting the same observable outcome. A divergence that is not listed in COMPATIBILITY.md is treated as a bug.

make test

Performance

Speedup versus stdlib asyncio on the same coroutines (free-threaded CPython 3.14.4, Apple M5 Max — 6 performance + 12 efficiency cores; median of 3 runs via bench/asyncio_bench.py, or make bench):

workload	1 thread	best
CPU work between awaits	1.21×	7.34× @16
each unit under `wait_for`	0.97×	6.59× @16
fan-out with `TaskGroup`	1.08×	5.72× @16
server handler (I/O + per-request work)	1.00×	5.28× @16
producer → queue → consumers	1.02×	3.88× @8
one shared `Lock`	0.95×	3.01× @4
pure scheduling, no per-task work	1.41×	1.60× @16
many real `sleep()` timers	0.51×	0.55× @4
create + cancel + unwind	0.62×	0.62× @1

Read that honestly. mt_asyncio is at rough parity per-thread and wins by parallelizing, so the more real work a task does between awaits, the better it does. Two things are genuinely slower: timers — each sleep() builds a Future, a TimerHandle and a helper coroutine where the runtime underneath needs only one native waiter — and cancellation, which is pure coordination and gets worse with more threads. Past 6 threads this machine is scheduling onto efficiency cores, so the 16-thread column is not 16 equal cores.

Benchmarks must be run against a release build (make build-release); the scripts refuse to run on a debug one, which is several times slower.

License

mt_asyncio is released under the BSD-3-Clause License, the same license as TonIO, whose copyright notice it retains. Ported CPython code is additionally covered by the PSF License Agreement. See LICENSE and NOTICE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mt_asyncio-0.1.0a1.tar.gz (104.4 kB view details)

Uploaded Jul 25, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

mt_asyncio-0.1.0a1-cp315-cp315t-musllinux_1_1_x86_64.whl (600.0 kB view details)

Uploaded Jul 25, 2026 CPython 3.15tmusllinux: musl 1.1+ x86-64

mt_asyncio-0.1.0a1-cp315-cp315t-musllinux_1_1_armv7l.whl (666.4 kB view details)

Uploaded Jul 25, 2026 CPython 3.15tmusllinux: musl 1.1+ ARMv7l

mt_asyncio-0.1.0a1-cp315-cp315t-musllinux_1_1_aarch64.whl (551.9 kB view details)

Uploaded Jul 25, 2026 CPython 3.15tmusllinux: musl 1.1+ ARM64

mt_asyncio-0.1.0a1-cp315-cp315t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (387.2 kB view details)

Uploaded Jul 25, 2026 CPython 3.15tmanylinux: glibc 2.17+ x86-64

mt_asyncio-0.1.0a1-cp315-cp315t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (389.5 kB view details)

Uploaded Jul 25, 2026 CPython 3.15tmanylinux: glibc 2.17+ ARMv7l

mt_asyncio-0.1.0a1-cp315-cp315t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (374.6 kB view details)

Uploaded Jul 25, 2026 CPython 3.15tmanylinux: glibc 2.17+ ARM64

mt_asyncio-0.1.0a1-cp315-cp315t-manylinux_2_12_i686.manylinux2010_i686.whl (414.7 kB view details)

Uploaded Jul 25, 2026 CPython 3.15tmanylinux: glibc 2.12+ i686

mt_asyncio-0.1.0a1-cp315-cp315t-macosx_11_0_arm64.whl (341.2 kB view details)

Uploaded Jul 25, 2026 CPython 3.15tmacOS 11.0+ ARM64

mt_asyncio-0.1.0a1-cp315-cp315t-macosx_10_12_x86_64.whl (358.0 kB view details)

Uploaded Jul 25, 2026 CPython 3.15tmacOS 10.12+ x86-64

mt_asyncio-0.1.0a1-cp314-cp314t-musllinux_1_1_x86_64.whl (600.2 kB view details)

Uploaded Jul 25, 2026 CPython 3.14tmusllinux: musl 1.1+ x86-64

mt_asyncio-0.1.0a1-cp314-cp314t-musllinux_1_1_armv7l.whl (666.2 kB view details)

Uploaded Jul 25, 2026 CPython 3.14tmusllinux: musl 1.1+ ARMv7l

mt_asyncio-0.1.0a1-cp314-cp314t-musllinux_1_1_aarch64.whl (552.1 kB view details)

Uploaded Jul 25, 2026 CPython 3.14tmusllinux: musl 1.1+ ARM64

mt_asyncio-0.1.0a1-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (387.3 kB view details)

Uploaded Jul 25, 2026 CPython 3.14tmanylinux: glibc 2.17+ x86-64

mt_asyncio-0.1.0a1-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (389.3 kB view details)

Uploaded Jul 25, 2026 CPython 3.14tmanylinux: glibc 2.17+ ARMv7l

mt_asyncio-0.1.0a1-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (374.8 kB view details)

Uploaded Jul 25, 2026 CPython 3.14tmanylinux: glibc 2.17+ ARM64

mt_asyncio-0.1.0a1-cp314-cp314t-manylinux_2_12_i686.manylinux2010_i686.whl (414.5 kB view details)

Uploaded Jul 25, 2026 CPython 3.14tmanylinux: glibc 2.12+ i686

mt_asyncio-0.1.0a1-cp314-cp314t-macosx_11_0_arm64.whl (341.4 kB view details)

Uploaded Jul 25, 2026 CPython 3.14tmacOS 11.0+ ARM64

mt_asyncio-0.1.0a1-cp314-cp314t-macosx_10_12_x86_64.whl (358.1 kB view details)

Uploaded Jul 25, 2026 CPython 3.14tmacOS 10.12+ x86-64

File details

Details for the file mt_asyncio-0.1.0a1.tar.gz.

File metadata

Download URL: mt_asyncio-0.1.0a1.tar.gz
Upload date: Jul 25, 2026
Size: 104.4 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for mt_asyncio-0.1.0a1.tar.gz
Algorithm	Hash digest
SHA256	`6625a45a36e8ce5e4d786bbce499038e7a9d8ccb6013631e634077433b7f607f`
MD5	`acd83e7a0a809cb764976aae45d1ddc9`
BLAKE2b-256	`52e49eb97fa6d776836b6dc44027f2035721ad32afa636aef220dc45a8e00832`

Algorithm	Hash digest
SHA256	`49660943c50d6a0bec29657ef5834b21c7df77ea76721a2619648fd490ae08ce`
MD5	`4f01712eecc16b3123d620857ec121cc`
BLAKE2b-256	`5e15d3844fc6d9e98a176b15a0285687df498a3048cbaffa6e7b81e40580e68f`

Algorithm	Hash digest
SHA256	`e9f05f972a5b5e00a5f5bfcd3ddbe78607fb2a76dcb4449f3f6b902fbe951f57`
MD5	`61c50c390aca48192f1f5066f968fedc`
BLAKE2b-256	`80a712385c3458e3743bf4f577e4487de1b27ed1b5654c77fd0dfd252399a858`

Algorithm	Hash digest
SHA256	`e9db8ca698d59f69af1c33eac513159e659027c5e15defdfb064fb2d54dccc7d`
MD5	`291cf3bdce57f18c75ec849e9dc8068b`
BLAKE2b-256	`f0bc8386706b081ff0edfb7716a17ef96f89a8beaaa912e5d76ae9e38ddfe6df`

Algorithm	Hash digest
SHA256	`9c9ff2697db74f744d38fee7a0f4ed567a87eb5daeae2dae23b93f38aa905863`
MD5	`d10c725c2c6b5a8e69934ea47c283580`
BLAKE2b-256	`ff781eab06fc9cbbd73389274071a076736b1e8d09b706e7ce4117c4de72c6df`

Algorithm	Hash digest
SHA256	`7411193b4919870da8c3306f9b6ca0f16a128f434d0c2b748df9c8e5d6006d9f`
MD5	`a7d9220093186dcb70fe82d4cdfd7ec5`
BLAKE2b-256	`4159d29736eeed6117b37ee3c8911de2b47994b59aa512a530f5b6c33a9eed21`

Algorithm	Hash digest
SHA256	`3b451486cc54b3d01abb960aa20c412229bdc79782e3b3f19778f404f0739059`
MD5	`3ea8fa34a653ffadccc2dd1959144656`
BLAKE2b-256	`6e0777bdf2d5048e9551618e76675b3efe9b52f439e2ddff640f7683d2ea6416`

Algorithm	Hash digest
SHA256	`db5c48cab2905ef0bfdf44bb8b1354c562d603ac606084c1f7585248209bf879`
MD5	`a99c46fe1fdcadbc6e6a4319f7bc017c`
BLAKE2b-256	`dfe07b999c7173c59507c7b0f2215110d4a1fbdd3aee2d71ebc265c6c04e0be1`

Algorithm	Hash digest
SHA256	`f51a6139665e870d3c59f6590e452392f9420379e616ec21b0c96d1d74752d27`
MD5	`bb162ef78f234590aeb72beacf5ba376`
BLAKE2b-256	`a1ecfcbed3e8e61d890c4513c5d2ad3b308ef8a0f8529668690038b86e4dd5ad`

Algorithm	Hash digest
SHA256	`661ffe3e67ffd1130b77eaf26ec37de6a00760c6f12051b568e45663d33dadd5`
MD5	`4adcc83d91f0ebf3e058ea24a561b913`
BLAKE2b-256	`52f068a1f3d26f5881d7007654fa492ae36198591da10dca97df84166b72503a`

Algorithm	Hash digest
SHA256	`0afcb5175ffc1983599b44b76b0adcb4c269674e5a2c0ff5c71bc63e3928d46f`
MD5	`eeddb05a884c5f715a1519ad38439435`
BLAKE2b-256	`81144059afb2fed0b1a44a60a0e933254843c94b6416da59b649e3a543518519`

Algorithm	Hash digest
SHA256	`710bdf90e2dbbe416cd4399328a59cd35821b411a9523eb807fd2006b31ee6f9`
MD5	`70f4fe1a5cb96a08b876483bc7bfe1a9`
BLAKE2b-256	`bb047ac4206c01b68cd483abac2302420cc82dcc835a3156ce37d95e2595bf75`

Algorithm	Hash digest
SHA256	`ffa3e2395bffaa934b9828551a5039398dcb8c7efe279409872414c1c3ed0d13`
MD5	`488137f279b40e2f240413934d233893`
BLAKE2b-256	`b75043d3d39dd49de5dd806c9c141a38066797c33f9b9da5c681f4b3f64eb070`

Algorithm	Hash digest
SHA256	`e19decfd5669f3aa1761a34eb312bcc591fcbb9e7609aad2eefd13a8f7275ca3`
MD5	`06f6f13d8bb48a082ca4ff293739122c`
BLAKE2b-256	`ae74205ef2c946f74351e1679e58fe480d09b021fd62b50917f1e6a1e25e06e8`

Algorithm	Hash digest
SHA256	`ff5fc753783c66c03cf7c769ad76d890e44dcafeabe6da6ffcffda110a350329`
MD5	`51febd1924a7a65cf4aacd8c2758fb43`
BLAKE2b-256	`d32dbb685cc3d4d499ab996b07a99f2e23f56d2cca1b941c894e3d3699b57b4e`

Algorithm	Hash digest
SHA256	`36b598efa9e680ccf5a47276a67199158393b1fabaf711df64a9824f7b25e93b`
MD5	`deabafa435b29b6635ee2445ea5414ab`
BLAKE2b-256	`f1576de96f99bd19ca69e5f736de9e48530d80dee2b9620b089ffc994965761d`

Algorithm	Hash digest
SHA256	`c60e3177181623dd0262b76fd84736b398bf043cebf8b5cc52777f9f1f16b9e1`
MD5	`0bd2d53d30d662475f892a8834a38973`
BLAKE2b-256	`97712d0c8564c6bbf3b1dae63bd09a7438ff29622d5389c834373b282c21e693`

Algorithm	Hash digest
SHA256	`e05e360c6535e1ab4b74f1aa95e8d55fc1bf7ba20f801fb0835c4d843ec76a78`
MD5	`0d20ba6ccc7625add7eb6a4aa0e63367`
BLAKE2b-256	`ef90f367d632dc9aee02db2d4b7ed65845247630917f18f460d6102da92f116c`

Algorithm	Hash digest
SHA256	`a474a36c664437437c062f7adea8d83f667a2081ba17613b75fcca2547f48c78`
MD5	`139852e0e3d82eb7b39c80b0352de3f5`
BLAKE2b-256	`9fdd3e4c6e0f7503b63c327aa9a36207738712504d5af6087e2dd0bc83fb9d68`

mt-asyncio 0.1.0a1

mt_asyncio

Why

Install

Usage

Third-party libraries

Blocking calls

Sizing the runtime

The drop-in boundary

Compatibility testing

Performance

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance