Run CPU bound code in subinterpreters using asyncio.
Installation
Pick the tool of your choosing
uv add aiointerpreters uv pip install aiointerpreters pip install aiointerpreters poetry add aiointerpreters pdm add aiointerpreters pipenv install aiointerpreters
Runner
See runner docs, initially the library only exposes a Runner class with a custom interface to schedule asyncio tasks.
Since the official release of 3.14 and the stablisation of a lot of the interpreter features, this offers no advantage to the standard library InterpreterPoolExecutor and therefore is not something that will be updated going forward.
Executor
This library implements a new InterpreterThreadPoolExecutor. This is a drop in replacement for the standard ThreadPoolExecutor with options to dynamically switch to using an Interpreter.
from aiointerpreters.executors import InterpreterThreadPoolExecutor, interpreter with InterpreterThreadPoolExecutor() as executor: executor.map(interpreter(cpu_bound), (argument for _ in range(runs)))
Any function tagged with interpreter decorator will be dispatched to an isolated interpreter in a separate thread. Otherwise this follows the original behaviour of ThreadPoolExecutor.
Additionally, InterpreterThreadPoolExecutor can be set as the default executor for asyncio and used with asyncio.to_thread:
# Shortcut InterpreterThreadPoolExecutor().set_as_event_loop_default() # or asyncio.get_running_loop().set_default_executor(InterpreterThreadPoolExecutor()) async with asyncio.TaskGroup() as tg: tg.create_task(asyncio.to_thread(interpreter(cpu_bound), argument)) tg.create_task(asyncio.to_thread(io_bound, argument))
Restrictions
The CPU bound function must be picklable. All its arguments and return value must be pickables or Shareable:
type Shareable = ( str | bytes | int | float | bool | None | tuple[Shareable, ...] | Queue | memoryview )
Motivation
concurrent.future.InterpreterPoolExecutor is currently a great choice if you know you always need an interpreter to run your code. However it's rarely something you want to do by default since you have to always consider the restrictions mentioned above.
You can choose to run a ThreadPoolExecutor alongside an InterpreterPoolExecutor but since they both maintain a pool of threads under the hood, it'll actually save some resources to share the pool of threads. And having one good default option just makes things easier.
Using asyncio.to_thread
Note: since ContextVars are not pickleable InterpreterThreadPoolExecutor works around it by discarding the context, this is not slightly hacky and may change in the future.
Examples
See examples.