# `concurrent.interpreters` — Multiple interpreters in the same process

Added in version 3.14.

Source code: Lib/concurrent/interpreters.py

## Introduction

The `concurrent.interpreters` module constructs higher-level interfaces on top of the lower level `_interpreters` module.

See also

Isolating Extension Modules

  how to update an extension module to support multiple interpreters

PEP 554

PEP 734

PEP 684

Availability: not WASI.

This module does not work or is not available on WebAssembly. See WebAssembly platforms for more information.

## Key details

Before we dive into examples, there are a small number of details to keep in mind about using multiple interpreters:

- isolated, by default

- no implicit threads

- not all PyPI packages support use in multiple interpreters yet

In the context of multiple interpreters, “isolated” means that different interpreters do not share any state. In practice, there is some process-global data they all share, but that is managed by the runtime.

## Reference

This module defines the following functions:

concurrent.interpreters.list_all()

  Return a `list` of `Interpreter` objects, one for each existing interpreter.

concurrent.interpreters.get_current()

  Return an `Interpreter` object for the currently running interpreter.

concurrent.interpreters.get_main()

  Return an `Interpreter` object for the main interpreter.

concurrent.interpreters.create()

  Initialize a new (idle) Python interpreter and return a `Interpreter` object for it.

### Interpreter objects

class concurrent.interpreters.Interpreter(id)

  A single interpreter in the current process.

  Generally, `Interpreter` shouldn’t be called directly. Instead, use `create()` or one of the other module functions.

  id

    (read-only)

    The interpreter’s ID.

  whence

    (read-only)

    A string describing where the interpreter came from.

  is_running()

    Return `True` if the interpreter is currently executing code in its `__main__` module and `False` otherwise.

  close()

    Finalize and destroy the interpreter.

  prepare_main(ns=None, **kwargs)

    Bind “shareable” objects in the interpreter’s `__main__` module.

  exec(code, /, dedent=True)

    Run the given source code in the interpreter (in the current thread).

  call(callable, /, *args, **kwargs)

    Return the result of calling running the given function in the interpreter (in the current thread).

  call_in_thread(callable, /, *args, **kwargs)

    Run the given function in the interpreter (in a new thread).

### Exceptions

exception concurrent.interpreters.InterpreterError

  This exception, a subclass of `Exception`, is raised when an interpreter-related error happens.

exception concurrent.interpreters.InterpreterNotFoundError

  This exception, a subclass of `InterpreterError`, is raised when the targeted interpreter no longer exists.

exception concurrent.interpreters.ExecutionFailed

  This exception, a subclass of `InterpreterError`, is raised when the running code raised an uncaught exception.

  excinfo

    A basic snapshot of the exception raised in the other interpreter.

exception concurrent.interpreters.NotShareableError

  This exception, a subclass of `TypeError`, is raised when an object cannot be sent to another interpreter.

## Basic usage

Creating an interpreter and running code in it:

    from concurrent import interpreters

    interp = interpreters.create()

    # Run in the current OS thread.

    interp.exec('print("spam!")')

    interp.exec("""if True:
        print('spam!')
        """)

    from textwrap import dedent
    interp.exec(dedent("""
        print('spam!')
        """))

    def run():
        print('spam!')

    interp.call(run)

    # Run in new OS thread.

    t = interp.call_in_thread(run)
    t.join()