Python support for free threading

Python support for free threading¶
Starting with the 3.13 release, CPython has support for a build of Python called free threading where the global interpreter lock (GIL) is disabled. Free-threaded execution allows for full utilization of the available processing power by running threads in parallel on available CPU cores. While not all software will benefit from this automatically, programs designed with threading in mind will run faster on multi-core hardware.
Some third-party packages, in particular ones with an extension module, may not be ready for use in a free-threaded build, and will re-enable the GIL.
This document describes the implications of free threading for Python code. See C API Extension Support for Free Threading for information on how to write C extensions that support the free-threaded build.
See also
PEP 703 – Making the Global Interpreter Lock Optional in CPython for an overall description of free-threaded Python.
Installation¶
Starting with Python 3.13, the official macOS and Windows installers optionally support installing free-threaded Python binaries. The installers are available at https://www.python.org/downloads/.
For information on other platforms, see the Installing a Free-Threaded Python, a community-maintained installation guide for installing free-threaded Python.
When building CPython from source, the --disable-gil
configure option
should be used to build a free-threaded Python interpreter.
Identifying free-threaded Python¶
To check if the current interpreter supports free-threading, python -VV
and sys.version
contain “free-threading build”.
The new sys._is_gil_enabled()
function can be used to check whether
the GIL is actually disabled in the running process.
The sysconfig.get_config_var("Py_GIL_DISABLED")
configuration variable can
be used to determine whether the build supports free threading. If the variable
is set to 1
, then the build supports free threading. This is the recommended
mechanism for decisions related to the build configuration.
The global interpreter lock in free-threaded Python¶
Free-threaded builds of CPython support optionally running with the GIL enabled
at runtime using the environment variable PYTHON_GIL
or
the command-line option -X gil
.
The GIL may also automatically be enabled when importing a C-API extension module that is not explicitly marked as supporting free threading. A warning will be printed in this case.
In addition to individual package documentation, the following websites track the status of popular packages support for free threading:
Thread safety¶
The free-threaded build of CPython aims to provide similar thread-safety
behavior at the Python level to the default GIL-enabled build. Built-in
types like dict
, list
, and set
use internal locks
to protect against concurrent modifications in ways that behave similarly to
the GIL. However, Python has not historically guaranteed specific behavior for
concurrent modifications to these built-in types, so this should be treated
as a description of the current implementation, not a guarantee of current or
future behavior.
Note
It’s recommended to use the threading.Lock
or other synchronization
primitives instead of relying on the internal locks of built-in types, when
possible.
Known limitations¶
This section describes known limitations of the free-threaded CPython build.
Immortalization¶
In the free-threaded build, some objects are immortal. Immortal objects are not deallocated and have reference counts that are never modified. This is done to avoid reference count contention that would prevent efficient multi-threaded scaling.
As of the 3.14 release, immortalization is limited to:
Code constants: numeric literals, string literals, and tuple literals composed of other constants.
Strings interned by
sys.intern()
.
Frame objects¶
It is not safe to access frame.f_locals
from a frame
object if that frame is currently executing in another thread, and doing so may
crash the interpreter.
Iterators¶
It is generally not thread-safe to access the same iterator object from multiple threads concurrently, and threads may see duplicate or missing elements.
Single-threaded performance¶
The free-threaded build has additional overhead when executing Python code compared to the default GIL-enabled build. The amount of overhead depends on the workload and hardware. On the pyperformance benchmark suite, the average overhead ranges from about 1% on macOS aarch64 to 8% on x86-64 Linux systems.
Behavioral changes¶
This section describes CPython behavioural changes with the free-threaded build.
Context variables¶
In the free-threaded build, the flag thread_inherit_context
is set to true by default which causes threads created with
threading.Thread
to start with a copy of the
Context()
of the caller of
start()
. In the default GIL-enabled build, the flag
defaults to false so threads start with an
empty Context()
.
Warning filters¶
In the free-threaded build, the flag context_aware_warnings
is set to true by default. In the default GIL-enabled build, the flag defaults
to false. If the flag is true then the warnings.catch_warnings
context manager uses a context variable for warning filters. If the flag is
false then catch_warnings
modifies the global filters list,
which is not thread-safe. See the warnings
module for more details.


Compound statements

8. Compound statements¶
Compound statements contain (groups of) other statements; they affect or control the execution of those other statements in some way. In general, compound statements span multiple lines, although in simple incarnations a whole compound statement may be contained in one line.
The if
, while
and for
statements implement
traditional control flow constructs. try
specifies exception
handlers and/or cleanup code for a group of statements, while the
with
statement allows the execution of initialization and
finalization code around a block of code. Function and class definitions are
also syntactically compound statements.
A compound statement consists of one or more ‘clauses.’ A clause consists of a
header and a ‘suite.’ The clause headers of a particular compound statement are
all at the same indentation level. Each clause header begins with a uniquely
identifying keyword and ends with a colon. A suite is a group of statements
controlled by a clause. A suite can be one or more semicolon-separated simple
statements on the same line as the header, following the header’s colon, or it
can be one or more indented statements on subsequent lines. Only the latter
form of a suite can contain nested compound statements; the following is illegal,
mostly because it wouldn’t be clear to which if
clause a following
else
clause would belong:
if test1: if test2: print(x)
Also note that the semicolon binds tighter than the colon in this context, so
that in the following example, either all or none of the print()
calls are
executed:
if x < y < z: print(x); print(y); print(z)
Summarizing:
compound_stmt:if_stmt
|while_stmt
|for_stmt
|try_stmt
|with_stmt
|match_stmt
|funcdef
|classdef
|async_with_stmt
|async_for_stmt
|async_funcdef
suite:stmt_list
NEWLINE | NEWLINE INDENTstatement
+ DEDENT statement:stmt_list
NEWLINE |compound_stmt
stmt_list:simple_stmt
(";"simple_stmt
)* [";"]
Note that statements always end in a NEWLINE
possibly followed by a
DEDENT
. Also note that optional continuation clauses always begin with a
keyword that cannot start a statement, thus there are no ambiguities (the
‘dangling else
’ problem is solved in Python by requiring nested
if
statements to be indented).
The formatting of the grammar rules in the following sections places each clause on a separate line for clarity.
8.1. The if
statement¶
The if
statement is used for conditional execution:
if_stmt: "if"assignment_expression
":"suite
("elif"assignment_expression
":"suite
)* ["else" ":"suite
]
It selects exactly one of the suites by evaluating the expressions one by one
until one is found to be true (see section Boolean operations for the definition of
true and false); then that suite is executed (and no other part of the
if
statement is executed or evaluated). If all expressions are
false, the suite of the else
clause, if present, is executed.
8.2. The while
statement¶
The while
statement is used for repeated execution as long as an
expression is true:
while_stmt: "while"assignment_expression
":"suite
["else" ":"suite
]
This repeatedly tests the expression and, if it is true, executes the first
suite; if the expression is false (which may be the first time it is tested) the
suite of the else
clause, if present, is executed and the loop
terminates.
A break
statement executed in the first suite terminates the loop
without executing the else
clause’s suite. A continue
statement executed in the first suite skips the rest of the suite and goes back
to testing the expression.
8.3. The for
statement¶
The for
statement is used to iterate over the elements of a sequence
(such as a string, tuple or list) or other iterable object:
for_stmt: "for"target_list
"in"starred_expression_list
":"suite
["else" ":"suite
]
The starred_expression_list
expression is evaluated
once; it should yield an iterable object. An iterator is
created for that iterable. The first item provided by the iterator is then
assigned to the target list using the standard rules for assignments
(see Assignment statements), and the suite is executed. This repeats for each
item provided by the iterator. When the iterator is exhausted,
the suite in the else
clause,
if present, is executed, and the loop terminates.
A break
statement executed in the first suite terminates the loop
without executing the else
clause’s suite. A continue
statement executed in the first suite skips the rest of the suite and continues
with the next item, or with the else
clause if there is no next
item.
The for-loop makes assignments to the variables in the target list. This overwrites all previous assignments to those variables including those made in the suite of the for-loop:
for i in range(10):
print(i)
i = 5 # this will not affect the for-loop
# because i will be overwritten with the next
# index in the range
Names in the target list are not deleted when the loop is finished, but if the
sequence is empty, they will not have been assigned to at all by the loop. Hint:
the built-in type range()
represents immutable arithmetic sequences of integers.
For instance, iterating range(3)
successively yields 0, 1, and then 2.
Changed in version 3.11: Starred elements are now allowed in the expression list.
8.4. The try
statement¶
The try
statement specifies exception handlers and/or cleanup code
for a group of statements:
try_stmt:try1_stmt
|try2_stmt
|try3_stmt
try1_stmt: "try" ":"suite
("except" [expression
["as"identifier
]] ":"suite
)+ ["else" ":"suite
] ["finally" ":"suite
] try2_stmt: "try" ":"suite
("except" "*"expression
["as"identifier
] ":"suite
)+ ["else" ":"suite
] ["finally" ":"suite
] try3_stmt: "try" ":"suite
"finally" ":"suite
Additional information on exceptions can be found in section Exceptions,
and information on using the raise
statement to generate exceptions
may be found in section The raise statement.
Changed in version 3.14: Support for optionally dropping grouping parentheses when using multiple exception types. See PEP 758.
8.4.1. except
clause¶
The except
clause(s) specify one or more exception handlers. When no
exception occurs in the try
clause, no exception handler is executed.
When an exception occurs in the try
suite, a search for an exception
handler is started. This search inspects the except
clauses in turn
until one is found that matches the exception.
An expression-less except
clause, if present, must be last;
it matches any exception.
For an except
clause with an expression, the
expression must evaluate to an exception type or a tuple of exception types. Parentheses
can be dropped if multiple exception types are provided and the as
clause is not used.
The raised exception matches an except
clause whose expression evaluates
to the class or a non-virtual base class of the exception object,
or to a tuple that contains such a class.
If no except
clause matches the exception,
the search for an exception handler
continues in the surrounding code and on the invocation stack. [1]
If the evaluation of an expression
in the header of an except
clause raises an exception,
the original search for a handler is canceled and a search starts for
the new exception in the surrounding code and on the call stack (it is treated
as if the entire try
statement raised the exception).
When a matching except
clause is found,
the exception is assigned to the target
specified after the as
keyword in that except
clause,
if present, and the except
clause’s suite is executed.
All except
clauses must have an executable block.
When the end of this block is reached, execution continues
normally after the entire try
statement.
(This means that if two nested handlers exist for the same exception,
and the exception occurs in the try
clause of the inner handler,
the outer handler will not handle the exception.)
When an exception has been assigned using as target
, it is cleared at the
end of the except
clause. This is as if
except E as N:
foo
was translated to
except E as N:
try:
foo
finally:
del N
This means the exception must be assigned to a different name to be able to
refer to it after the except
clause.
Exceptions are cleared because with the
traceback attached to them, they form a reference cycle with the stack frame,
keeping all locals in that frame alive until the next garbage collection occurs.
Before an except
clause’s suite is executed,
the exception is stored in the sys
module, where it can be accessed
from within the body of the except
clause by calling
sys.exception()
. When leaving an exception handler, the exception
stored in the sys
module is reset to its previous value:
>>> print(sys.exception())
None
>>> try:
... raise TypeError
... except:
... print(repr(sys.exception()))
... try:
... raise ValueError
... except:
... print(repr(sys.exception()))
... print(repr(sys.exception()))
...
TypeError()
ValueError()
TypeError()
>>> print(sys.exception())
None
8.4.2. except*
clause¶
The except*
clause(s) specify one or more handlers for groups of
exceptions (BaseExceptionGroup
instances). A try
statement
can have either except
or except*
clauses, but not both.
The exception type for matching is mandatory in the case of except*
,
so except*:
is a syntax error. The type is interpreted as in the case of
except
, but matching is performed on the exceptions contained in the
group that is being handled. An TypeError
is raised if a matching
type is a subclass of BaseExceptionGroup
, because that would have
ambiguous semantics.
When an exception group is raised in the try block, each except*
clause splits (see split()
) it into the subgroups
of matching and non-matching exceptions. If the matching subgroup is not empty,
it becomes the handled exception (the value returned from sys.exception()
)
and assigned to the target of the except*
clause (if there is one).
Then, the body of the except*
clause executes. If the non-matching
subgroup is not empty, it is processed by the next except*
in the
same manner. This continues until all exceptions in the group have been matched,
or the last except*
clause has run.
After all except*
clauses execute, the group of unhandled exceptions
is merged with any exceptions that were raised or re-raised from within
except*
clauses. This merged exception group propagates on.:
>>> try:
... raise ExceptionGroup("eg",
... [ValueError(1), TypeError(2), OSError(3), OSError(4)])
... except* TypeError as e:
... print(f'caught {type(e)} with nested {e.exceptions}')
... except* OSError as e:
... print(f'caught {type(e)} with nested {e.exceptions}')
...
caught <class 'ExceptionGroup'> with nested (TypeError(2),)
caught <class 'ExceptionGroup'> with nested (OSError(3), OSError(4))
+ Exception Group Traceback (most recent call last):
| File "<doctest default[0]>", line 2, in <module>
| raise ExceptionGroup("eg",
| [ValueError(1), TypeError(2), OSError(3), OSError(4)])
| ExceptionGroup: eg (1 sub-exception)
+-+---------------- 1 ----------------
| ValueError: 1
+------------------------------------
If the exception raised from the try
block is not an exception group
and its type matches one of the except*
clauses, it is caught and
wrapped by an exception group with an empty message string. This ensures that the
type of the target e
is consistently BaseExceptionGroup
:
>>> try:
... raise BlockingIOError
... except* BlockingIOError as e:
... print(repr(e))
...
ExceptionGroup('', (BlockingIOError(),))
break
, continue
and return
cannot appear in an except*
clause.
8.4.3. else
clause¶
The optional else
clause is executed if the control flow leaves the
try
suite, no exception was raised, and no return
,
continue
, or break
statement was executed. Exceptions in
the else
clause are not handled by the preceding except
clauses.
8.4.4. finally
clause¶
If finally
is present, it specifies a ‘cleanup’ handler. The
try
clause is executed, including any except
and else
clauses.
If an exception occurs in any of the clauses and is not handled,
the exception is temporarily saved.
The finally
clause is executed. If there is a saved exception
it is re-raised at the end of the finally
clause.
If the finally
clause raises another exception, the saved exception
is set as the context of the new exception.
If the finally
clause executes a return
, break
or continue
statement, the saved exception is discarded. For example,
this function returns 42.
def f():
try:
1/0
finally:
return 42
The exception information is not available to the program during execution of
the finally
clause.
When a return
, break
or continue
statement is
executed in the try
suite of a try
…finally
statement, the finally
clause is also executed ‘on the way out.’
The return value of a function is determined by the last return
statement executed. Since the finally
clause always executes, a
return
statement executed in the finally
clause will
always be the last one executed. The following function returns ‘finally’.
def foo():
try:
return 'try'
finally:
return 'finally'
Changed in version 3.8: Prior to Python 3.8, a continue
statement was illegal in the
finally
clause due to a problem with the implementation.
Changed in version 3.14: The compiler emits a SyntaxWarning
when a return
,
break
or continue
appears in a finally
block (see PEP 765).
8.5. The with
statement¶
The with
statement is used to wrap the execution of a block with
methods defined by a context manager (see section With Statement Context Managers).
This allows common try
…except
…finally
usage patterns to be encapsulated for convenient reuse.
with_stmt: "with" ( "("with_stmt_contents
","? ")" |with_stmt_contents
) ":"suite
with_stmt_contents:with_item
(","with_item
)* with_item:expression
["as"target
]
The execution of the with
statement with one “item” proceeds as follows:
The context expression (the expression given in the
with_item
) is evaluated to obtain a context manager.The context manager’s
__enter__()
is loaded for later use.The context manager’s
__exit__()
is loaded for later use.The context manager’s
__enter__()
method is invoked.If a target was included in the
with
statement, the return value from__enter__()
is assigned to it.Note
The
with
statement guarantees that if the__enter__()
method returns without an error, then__exit__()
will always be called. Thus, if an error occurs during the assignment to the target list, it will be treated the same as an error occurring within the suite would be. See step 7 below.The suite is executed.
The context manager’s
__exit__()
method is invoked. If an exception caused the suite to be exited, its type, value, and traceback are passed as arguments to__exit__()
. Otherwise, threeNone
arguments are supplied.If the suite was exited due to an exception, and the return value from the
__exit__()
method was false, the exception is reraised. If the return value was true, the exception is suppressed, and execution continues with the statement following thewith
statement.If the suite was exited for any reason other than an exception, the return value from
__exit__()
is ignored, and execution proceeds at the normal location for the kind of exit that was taken.
The following code:
with EXPRESSION as TARGET:
SUITE
is semantically equivalent to:
manager = (EXPRESSION)
enter = manager.__enter__
exit = manager.__exit__
value = enter()
hit_except = False
try:
TARGET = value
SUITE
except:
hit_except = True
if not exit(*sys.exc_info()):
raise
finally:
if not hit_except:
exit(None, None, None)
except that implicit special method lookup is used
for __enter__()
and __exit__()
.
With more than one item, the context managers are processed as if multiple
with
statements were nested:
with A() as a, B() as b:
SUITE
is semantically equivalent to:
with A() as a:
with B() as b:
SUITE
You can also write multi-item context managers in multiple lines if the items are surrounded by parentheses. For example:
with (
A() as a,
B() as b,
):
SUITE
Changed in version 3.1: Support for multiple context expressions.
Changed in version 3.10: Support for using grouping parentheses to break the statement in multiple lines.
8.6. The match
statement¶
Added in version 3.10.
The match statement is used for pattern matching. Syntax:
match_stmt: 'match'subject_expr
":" NEWLINE INDENTcase_block
+ DEDENT subject_expr: `!star_named_expression` "," `!star_named_expressions`? | `!named_expression` case_block: 'case'patterns
[guard
] ":" `!block`
Note
This section uses single quotes to denote soft keywords.
Pattern matching takes a pattern as input (following case
) and a subject
value (following match
). The pattern (which may contain subpatterns) is
matched against the subject value. The outcomes are:
A match success or failure (also termed a pattern success or failure).
Possible binding of matched values to a name. The prerequisites for this are further discussed below.
The match
and case
keywords are soft keywords.
See also
8.6.1. Overview¶
Here’s an overview of the logical flow of a match statement:
The subject expression
subject_expr
is evaluated and a resulting subject value obtained. If the subject expression contains a comma, a tuple is constructed using the standard rules.Each pattern in a
case_block
is attempted to match with the subject value. The specific rules for success or failure are described below. The match attempt can also bind some or all of the standalone names within the pattern. The precise pattern binding rules vary per pattern type and are specified below. Name bindings made during a successful pattern match outlive the executed block and can be used after the match statement.Note
During failed pattern matches, some subpatterns may succeed. Do not rely on bindings being made for a failed match. Conversely, do not rely on variables remaining unchanged after a failed match. The exact behavior is dependent on implementation and may vary. This is an intentional decision made to allow different implementations to add optimizations.
If the pattern succeeds, the corresponding guard (if present) is evaluated. In this case all name bindings are guaranteed to have happened.
If the guard evaluates as true or is missing, the
block
insidecase_block
is executed.Otherwise, the next
case_block
is attempted as described above.If there are no further case blocks, the match statement is completed.
Note
Users should generally never rely on a pattern being evaluated. Depending on implementation, the interpreter may cache values or use other optimizations which skip repeated evaluations.
A sample match statement:
>>> flag = False
>>> match (100, 200):
... case (100, 300): # Mismatch: 200 != 300
... print('Case 1')
... case (100, 200) if flag: # Successful match, but guard fails
... print('Case 2')
... case (100, y): # Matches and binds y to 200
... print(f'Case 3, y: {y}')
... case _: # Pattern not attempted
... print('Case 4, I match anything!')
...
Case 3, y: 200
In this case, if flag
is a guard. Read more about that in the next section.
8.6.2. Guards¶
guard: "if" `!named_expression`
A guard
(which is part of the case
) must succeed for code inside
the case
block to execute. It takes the form: if
followed by an
expression.
The logical flow of a case
block with a guard
follows:
Check that the pattern in the
case
block succeeded. If the pattern failed, theguard
is not evaluated and the nextcase
block is checked.If the pattern succeeded, evaluate the
guard
.If the
guard
condition evaluates as true, the case block is selected.If the
guard
condition evaluates as false, the case block is not selected.If the
guard
raises an exception during evaluation, the exception bubbles up.
Guards are allowed to have side effects as they are expressions. Guard evaluation must proceed from the first to the last case block, one at a time, skipping case blocks whose pattern(s) don’t all succeed. (I.e., guard evaluation must happen in order.) Guard evaluation must stop once a case block is selected.
8.6.3. Irrefutable Case Blocks¶
An irrefutable case block is a match-all case block. A match statement may have at most one irrefutable case block, and it must be last.
A case block is considered irrefutable if it has no guard and its pattern is irrefutable. A pattern is considered irrefutable if we can prove from its syntax alone that it will always succeed. Only the following patterns are irrefutable:
AS Patterns whose left-hand side is irrefutable
OR Patterns containing at least one irrefutable pattern
parenthesized irrefutable patterns
8.6.4. Patterns¶
Note
This section uses grammar notations beyond standard EBNF:
the notation
SEP.RULE+
is shorthand forRULE (SEP RULE)*
the notation
!RULE
is shorthand for a negative lookahead assertion
The top-level syntax for patterns
is:
patterns:open_sequence_pattern
|pattern
pattern:as_pattern
|or_pattern
closed_pattern: |literal_pattern
|capture_pattern
|wildcard_pattern
|value_pattern
|group_pattern
|sequence_pattern
|mapping_pattern
|class_pattern
The descriptions below will include a description “in simple terms” of what a pattern does for illustration purposes (credits to Raymond Hettinger for a document that inspired most of the descriptions). Note that these descriptions are purely for illustration purposes and may not reflect the underlying implementation. Furthermore, they do not cover all valid forms.
8.6.4.1. OR Patterns¶
An OR pattern is two or more patterns separated by vertical
bars |
. Syntax:
or_pattern: "|".closed_pattern
+
Only the final subpattern may be irrefutable, and each subpattern must bind the same set of names to avoid ambiguity.
An OR pattern matches each of its subpatterns in turn to the subject value, until one succeeds. The OR pattern is then considered successful. Otherwise, if none of the subpatterns succeed, the OR pattern fails.
In simple terms, P1 | P2 | ...
will try to match P1
, if it fails it will try to
match P2
, succeeding immediately if any succeeds, failing otherwise.
8.6.4.2. AS Patterns¶
An AS pattern matches an OR pattern on the left of the as
keyword against a subject. Syntax:
as_pattern:or_pattern
"as"capture_pattern
If the OR pattern fails, the AS pattern fails. Otherwise, the AS pattern binds
the subject to the name on the right of the as keyword and succeeds.
capture_pattern
cannot be a _
.
In simple terms P as NAME
will match with P
, and on success it will
set NAME = <subject>
.
8.6.4.3. Literal Patterns¶
A literal pattern corresponds to most literals in Python. Syntax:
literal_pattern:signed_number
|signed_number
"+" NUMBER |signed_number
"-" NUMBER |strings
| "None" | "True" | "False" signed_number: ["-"] NUMBER
The rule strings
and the token NUMBER
are defined in the
standard Python grammar. Triple-quoted strings are
supported. Raw strings and byte strings are supported. f-strings
and t-strings are not supported.
The forms signed_number '+' NUMBER
and signed_number '-' NUMBER
are
for expressing complex numbers; they require a real number
on the left and an imaginary number on the right. E.g. 3 + 4j
.
In simple terms, LITERAL
will succeed only if <subject> == LITERAL
. For
the singletons None
, True
and False
, the is
operator is used.
8.6.4.4. Capture Patterns¶
A capture pattern binds the subject value to a name. Syntax:
capture_pattern: !'_' NAME
A single underscore _
is not a capture pattern (this is what !'_'
expresses). It is instead treated as a
wildcard_pattern
.
In a given pattern, a given name can only be bound once. E.g.
case x, x: ...
is invalid while case [x] | x: ...
is allowed.
Capture patterns always succeed. The binding follows scoping rules
established by the assignment expression operator in PEP 572; the
name becomes a local variable in the closest containing function scope unless
there’s an applicable global
or nonlocal
statement.
In simple terms NAME
will always succeed and it will set NAME = <subject>
.
8.6.4.5. Wildcard Patterns¶
A wildcard pattern always succeeds (matches anything) and binds no name. Syntax:
wildcard_pattern: '_'
_
is a soft keyword within any pattern,
but only within patterns. It is an identifier, as usual, even within
match
subject expressions, guard
s, and case
blocks.
In simple terms, _
will always succeed.
8.6.4.6. Value Patterns¶
A value pattern represents a named value in Python. Syntax:
value_pattern:attr
attr:name_or_attr
"." NAME name_or_attr:attr
| NAME
The dotted name in the pattern is looked up using standard Python
name resolution rules. The pattern succeeds if the
value found compares equal to the subject value (using the ==
equality
operator).
In simple terms NAME1.NAME2
will succeed only if <subject> == NAME1.NAME2
Note
If the same value occurs multiple times in the same match statement, the interpreter may cache the first value found and reuse it rather than repeat the same lookup. This cache is strictly tied to a given execution of a given match statement.
8.6.4.7. Group Patterns¶
A group pattern allows users to add parentheses around patterns to emphasize the intended grouping. Otherwise, it has no additional syntax. Syntax:
group_pattern: "(" pattern
")"
In simple terms (P)
has the same effect as P
.
8.6.4.8. Sequence Patterns¶
A sequence pattern contains several subpatterns to be matched against sequence elements. The syntax is similar to the unpacking of a list or tuple.
sequence_pattern: "[" [maybe_sequence_pattern
] "]" | "(" [open_sequence_pattern
] ")" open_sequence_pattern:maybe_star_pattern
"," [maybe_sequence_pattern
] maybe_sequence_pattern: ",".maybe_star_pattern
+ ","? maybe_star_pattern:star_pattern
|pattern
star_pattern: "*" (capture_pattern
|wildcard_pattern
)
There is no difference if parentheses or square brackets
are used for sequence patterns (i.e. (...)
vs [...]
).
Note
A single pattern enclosed in parentheses without a trailing comma
(e.g. (3 | 4)
) is a group pattern.
While a single pattern enclosed in square brackets (e.g. [3 | 4]
) is
still a sequence pattern.
At most one star subpattern may be in a sequence pattern. The star subpattern may occur in any position. If no star subpattern is present, the sequence pattern is a fixed-length sequence pattern; otherwise it is a variable-length sequence pattern.
The following is the logical flow for matching a sequence pattern against a subject value:
If the subject value is not a sequence [2], the sequence pattern fails.
If the subject value is an instance of
str
,bytes
orbytearray
the sequence pattern fails.The subsequent steps depend on whether the sequence pattern is fixed or variable-length.
If the sequence pattern is fixed-length:
If the length of the subject sequence is not equal to the number of subpatterns, the sequence pattern fails
Subpatterns in the sequence pattern are matched to their corresponding items in the subject sequence from left to right. Matching stops as soon as a subpattern fails. If all subpatterns succeed in matching their corresponding item, the sequence pattern succeeds.
Otherwise, if the sequence pattern is variable-length:
If the length of the subject sequence is less than the number of non-star subpatterns, the sequence pattern fails.
The leading non-star subpatterns are matched to their corresponding items as for fixed-length sequences.
If the previous step succeeds, the star subpattern matches a list formed of the remaining subject items, excluding the remaining items corresponding to non-star subpatterns following the star subpattern.
Remaining non-star subpatterns are matched to their corresponding subject items, as for a fixed-length sequence.
Note
The length of the subject sequence is obtained via
len()
(i.e. via the__len__()
protocol). This length may be cached by the interpreter in a similar manner as value patterns.
In simple terms [P1, P2, P3,
… , P<N>]
matches only if all the following
happens:
check
<subject>
is a sequencelen(subject) == <N>
P1
matches<subject>[0]
(note that this match can also bind names)P2
matches<subject>[1]
(note that this match can also bind names)… and so on for the corresponding pattern/element.
8.6.4.9. Mapping Patterns¶
A mapping pattern contains one or more key-value patterns. The syntax is similar to the construction of a dictionary. Syntax:
mapping_pattern: "{" [items_pattern
] "}" items_pattern: ",".key_value_pattern
+ ","? key_value_pattern: (literal_pattern
|value_pattern
) ":"pattern
|double_star_pattern
double_star_pattern: "**"capture_pattern
At most one double star pattern may be in a mapping pattern. The double star pattern must be the last subpattern in the mapping pattern.
Duplicate keys in mapping patterns are disallowed. Duplicate literal keys will
raise a SyntaxError
. Two keys that otherwise have the same value will
raise a ValueError
at runtime.
The following is the logical flow for matching a mapping pattern against a subject value:
If the subject value is not a mapping [3],the mapping pattern fails.
If every key given in the mapping pattern is present in the subject mapping, and the pattern for each key matches the corresponding item of the subject mapping, the mapping pattern succeeds.
If duplicate keys are detected in the mapping pattern, the pattern is considered invalid. A
SyntaxError
is raised for duplicate literal values; or aValueError
for named keys of the same value.
Note
Key-value pairs are matched using the two-argument form of the mapping
subject’s get()
method. Matched key-value pairs must already be present
in the mapping, and not created on-the-fly via __missing__()
or __getitem__()
.
In simple terms {KEY1: P1, KEY2: P2, ... }
matches only if all the following
happens:
check
<subject>
is a mappingKEY1 in <subject>
P1
matches<subject>[KEY1]
… and so on for the corresponding KEY/pattern pair.
8.6.4.10. Class Patterns¶
A class pattern represents a class and its positional and keyword arguments (if any). Syntax:
class_pattern:name_or_attr
"(" [pattern_arguments
","?] ")" pattern_arguments:positional_patterns
[","keyword_patterns
] |keyword_patterns
positional_patterns: ",".pattern
+ keyword_patterns: ",".keyword_pattern
+ keyword_pattern: NAME "="pattern
The same keyword should not be repeated in class patterns.
The following is the logical flow for matching a class pattern against a subject value:
If
name_or_attr
is not an instance of the builtintype
, raiseTypeError
.If the subject value is not an instance of
name_or_attr
(tested viaisinstance()
), the class pattern fails.If no pattern arguments are present, the pattern succeeds. Otherwise, the subsequent steps depend on whether keyword or positional argument patterns are present.
For a number of built-in types (specified below), a single positional subpattern is accepted which will match the entire subject; for these types keyword patterns also work as for other types.
If only keyword patterns are present, they are processed as follows, one by one:
The keyword is looked up as an attribute on the subject.
If this raises an exception other than
AttributeError
, the exception bubbles up.If this raises
AttributeError
, the class pattern has failed.Else, the subpattern associated with the keyword pattern is matched against the subject’s attribute value. If this fails, the class pattern fails; if this succeeds, the match proceeds to the next keyword.
If all keyword patterns succeed, the class pattern succeeds.
If any positional patterns are present, they are converted to keyword patterns using the
__match_args__
attribute on the classname_or_attr
before matching:The equivalent of
getattr(cls, "__match_args__", ())
is called.If this raises an exception, the exception bubbles up.
If the returned value is not a tuple, the conversion fails and
TypeError
is raised.If there are more positional patterns than
len(cls.__match_args__)
,TypeError
is raised.Otherwise, positional pattern
i
is converted to a keyword pattern using__match_args__[i]
as the keyword.__match_args__[i]
must be a string; if notTypeError
is raised.If there are duplicate keywords,
TypeError
is raised.
Once all positional patterns have been converted to keyword patterns, the match proceeds as if there were only keyword patterns.
For the following built-in types the handling of positional subpatterns is different:
These classes accept a single positional argument, and the pattern there is matched against the whole object rather than an attribute. For example
int(0|1)
matches the value0
, but not the value0.0
.
In simple terms CLS(P1, attr=P2)
matches only if the following happens:
isinstance(<subject>, CLS)
convert
P1
to a keyword pattern usingCLS.__match_args__
For each keyword argument
attr=P2
:hasattr(<subject>, "attr")
P2
matches<subject>.attr
… and so on for the corresponding keyword argument/pattern pair.
8.7. Function definitions¶
A function definition defines a user-defined function object (see section The standard type hierarchy):
funcdef: [decorators
] "def"funcname
[type_params
] "(" [parameter_list
] ")" ["->"expression
] ":"suite
decorators:decorator
+ decorator: "@"assignment_expression
NEWLINE parameter_list:defparameter
(","defparameter
)* "," "/" ["," [parameter_list_no_posonly
]] |parameter_list_no_posonly
parameter_list_no_posonly:defparameter
(","defparameter
)* ["," [parameter_list_starargs
]] |parameter_list_starargs
parameter_list_starargs: "*" [star_parameter
] (","defparameter
)* ["," [parameter_star_kwargs
]] | "*" (","defparameter
)+ ["," [parameter_star_kwargs
]] |parameter_star_kwargs
parameter_star_kwargs: "**"parameter
[","] parameter:identifier
[":"expression
] star_parameter:identifier
[":" ["*"]expression
] defparameter:parameter
["="expression
] funcname:identifier
A function definition is an executable statement. Its execution binds the function name in the current local namespace to a function object (a wrapper around the executable code for the function). This function object contains a reference to the current global namespace as the global namespace to be used when the function is called.
The function definition does not execute the function body; this gets executed only when the function is called. [4]
A function definition may be wrapped by one or more decorator expressions. Decorator expressions are evaluated when the function is defined, in the scope that contains the function definition. The result must be a callable, which is invoked with the function object as the only argument. The returned value is bound to the function name instead of the function object. Multiple decorators are applied in nested fashion. For example, the following code
@f1(arg)
@f2
def func(): pass
is roughly equivalent to
def func(): pass
func = f1(arg)(f2(func))
except that the original function is not temporarily bound to the name func
.
Changed in version 3.9: Functions may be decorated with any valid
assignment_expression
. Previously, the grammar was
much more restrictive; see PEP 614 for details.
A list of type parameters may be given in square brackets
between the function’s name and the opening parenthesis for its parameter list.
This indicates to static type checkers that the function is generic. At runtime,
the type parameters can be retrieved from the function’s
__type_params__
attribute. See Generic functions for more.
Changed in version 3.12: Type parameter lists are new in Python 3.12.
When one or more parameters have the form parameter =
expression, the function is said to have “default parameter values.” For a
parameter with a default value, the corresponding argument may be
omitted from a call, in which
case the parameter’s default value is substituted. If a parameter has a default
value, all following parameters up until the “*
” must also have a default
value — this is a syntactic restriction that is not expressed by the grammar.
Default parameter values are evaluated from left to right when the function
definition is executed. This means that the expression is evaluated once, when
the function is defined, and that the same “pre-computed” value is used for each
call. This is especially important to understand when a default parameter value is a
mutable object, such as a list or a dictionary: if the function modifies the
object (e.g. by appending an item to a list), the default parameter value is in effect
modified. This is generally not what was intended. A way around this is to use
None
as the default, and explicitly test for it in the body of the function,
e.g.:
def whats_on_the_telly(penguin=None):
if penguin is None:
penguin = []
penguin.append("property of the zoo")
return penguin
Function call semantics are described in more detail in section Calls. A
function call always assigns values to all parameters mentioned in the parameter
list, either from positional arguments, from keyword arguments, or from default
values. If the form “*identifier
” is present, it is initialized to a tuple
receiving any excess positional parameters, defaulting to the empty tuple.
If the form “**identifier
” is present, it is initialized to a new
ordered mapping receiving any excess keyword arguments, defaulting to a
new empty mapping of the same type. Parameters after “*
” or
“*identifier
” are keyword-only parameters and may only be passed
by keyword arguments. Parameters before “/
” are positional-only parameters
and may only be passed by positional arguments.
Changed in version 3.8: The /
function parameter syntax may be used to indicate positional-only
parameters. See PEP 570 for details.
Parameters may have an annotation of the form “: expression
”
following the parameter name. Any parameter may have an annotation, even those of the form
*identifier
or **identifier
. (As a special case, parameters of the form
*identifier
may have an annotation “: *expression
”.) Functions may have “return” annotation of
the form “-> expression
” after the parameter list. These annotations can be
any valid Python expression. The presence of annotations does not change the
semantics of a function. See Annotations for more information on annotations.
Changed in version 3.11: Parameters of the form “*identifier
” may have an annotation
“: *expression
”. See PEP 646.
It is also possible to create anonymous functions (functions not bound to a
name), for immediate use in expressions. This uses lambda expressions, described in
section Lambdas. Note that the lambda expression is merely a shorthand for a
simplified function definition; a function defined in a “def
”
statement can be passed around or assigned to another name just like a function
defined by a lambda expression. The “def
” form is actually more powerful
since it allows the execution of multiple statements and annotations.
Programmer’s note: Functions are first-class objects. A “def
” statement
executed inside a function definition defines a local function that can be
returned or passed around. Free variables used in the nested function can
access the local variables of the function containing the def. See section
Naming and binding for details.
See also
- PEP 3107 - Function Annotations
The original specification for function annotations.
- PEP 484 - Type Hints
Definition of a standard meaning for annotations: type hints.
- PEP 526 - Syntax for Variable Annotations
Ability to type hint variable declarations, including class variables and instance variables.
- PEP 563 - Postponed Evaluation of Annotations
Support for forward references within annotations by preserving annotations in a string form at runtime instead of eager evaluation.
- PEP 318 - Decorators for Functions and Methods
Function and method decorators were introduced. Class decorators were introduced in PEP 3129.
8.8. Class definitions¶
A class definition defines a class object (see section The standard type hierarchy):
classdef: [decorators
] "class"classname
[type_params
] [inheritance
] ":"suite
inheritance: "(" [argument_list
] ")" classname:identifier
A class definition is an executable statement. The inheritance list usually
gives a list of base classes (see Metaclasses for more advanced uses), so
each item in the list should evaluate to a class object which allows
subclassing. Classes without an inheritance list inherit, by default, from the
base class object
; hence,
class Foo:
pass
is equivalent to
class Foo(object):
pass
The class’s suite is then executed in a new execution frame (see Naming and binding), using a newly created local namespace and the original global namespace. (Usually, the suite contains mostly function definitions.) When the class’s suite finishes execution, its execution frame is discarded but its local namespace is saved. [5] A class object is then created using the inheritance list for the base classes and the saved local namespace for the attribute dictionary. The class name is bound to this class object in the original local namespace.
The order in which attributes are defined in the class body is preserved
in the new class’s __dict__
. Note that this is reliable only right
after the class is created and only for classes that were defined using
the definition syntax.
Class creation can be customized heavily using metaclasses.
Classes can also be decorated: just like when decorating functions,
@f1(arg)
@f2
class Foo: pass
is roughly equivalent to
class Foo: pass
Foo = f1(arg)(f2(Foo))
The evaluation rules for the decorator expressions are the same as for function decorators. The result is then bound to the class name.
Changed in version 3.9: Classes may be decorated with any valid
assignment_expression
. Previously, the grammar was
much more restrictive; see PEP 614 for details.
A list of type parameters may be given in square brackets
immediately after the class’s name.
This indicates to static type checkers that the class is generic. At runtime,
the type parameters can be retrieved from the class’s
__type_params__
attribute. See Generic classes for more.
Changed in version 3.12: Type parameter lists are new in Python 3.12.
Programmer’s note: Variables defined in the class definition are class
attributes; they are shared by instances. Instance attributes can be set in a
method with self.name = value
. Both class and instance attributes are
accessible through the notation “self.name
”, and an instance attribute hides
a class attribute with the same name when accessed in this way. Class
attributes can be used as defaults for instance attributes, but using mutable
values there can lead to unexpected results. Descriptors
can be used to create instance variables with different implementation details.
See also
- PEP 3115 - Metaclasses in Python 3000
The proposal that changed the declaration of metaclasses to the current syntax, and the semantics for how classes with metaclasses are constructed.
- PEP 3129 - Class Decorators
The proposal that added class decorators. Function and method decorators were introduced in PEP 318.
8.9. Coroutines¶
Added in version 3.5.
8.9.1. Coroutine function definition¶
async_funcdef: [decorators
] "async" "def"funcname
"(" [parameter_list
] ")" ["->"expression
] ":"suite
Execution of Python coroutines can be suspended and resumed at many points
(see coroutine). await
expressions, async for
and
async with
can only be used in the body of a coroutine function.
Functions defined with async def
syntax are always coroutine functions,
even if they do not contain await
or async
keywords.
It is a SyntaxError
to use a yield from
expression inside the body
of a coroutine function.
An example of a coroutine function:
async def func(param1, param2):
do_stuff()
await some_coroutine()
Changed in version 3.7: await
and async
are now keywords; previously they were only
treated as such inside the body of a coroutine function.
8.9.2. The async for
statement¶
async_for_stmt: "async" for_stmt
An asynchronous iterable provides an __aiter__
method that directly
returns an asynchronous iterator, which can call asynchronous code in
its __anext__
method.
The async for
statement allows convenient iteration over asynchronous
iterables.
The following code:
async for TARGET in ITER:
SUITE
else:
SUITE2
Is semantically equivalent to:
iter = (ITER).__aiter__()
running = True
while running:
try:
TARGET = await iter.__anext__()
except StopAsyncIteration:
running = False
else:
SUITE
else:
SUITE2
except that implicit special method lookup is used
for __aiter__()
and __anext__()
.
It is a SyntaxError
to use an async for
statement outside the
body of a coroutine function.
8.9.3. The async with
statement¶
async_with_stmt: "async" with_stmt
An asynchronous context manager is a context manager that is able to suspend execution in its enter and exit methods.
The following code:
async with EXPRESSION as TARGET:
SUITE
is semantically equivalent to:
manager = (EXPRESSION)
aenter = manager.__aenter__
aexit = manager.__aexit__
value = await aenter()
hit_except = False
try:
TARGET = value
SUITE
except:
hit_except = True
if not await aexit(*sys.exc_info()):
raise
finally:
if not hit_except:
await aexit(None, None, None)
except that implicit special method lookup is used
for __aenter__()
and __aexit__()
.
It is a SyntaxError
to use an async with
statement outside the
body of a coroutine function.
See also
- PEP 492 - Coroutines with async and await syntax
The proposal that made coroutines a proper standalone concept in Python, and added supporting syntax.
8.10. Type parameter lists¶
Added in version 3.12.
Changed in version 3.13: Support for default values was added (see PEP 696).
type_params: "["type_param
(","type_param
)* "]" type_param:typevar
|typevartuple
|paramspec
typevar:identifier
(":"expression
)? ("="expression
)? typevartuple: "*"identifier
("="expression
)? paramspec: "**"identifier
("="expression
)?
Functions (including coroutines), classes and type aliases may contain a type parameter list:
def max[T](args: list[T]) -> T:
...
async def amax[T](args: list[T]) -> T:
...
class Bag[T]:
def __iter__(self) -> Iterator[T]:
...
def add(self, arg: T) -> None:
...
type ListOrSet[T] = list[T] | set[T]
Semantically, this indicates that the function, class, or type alias is generic over a type variable. This information is primarily used by static type checkers, and at runtime, generic objects behave much like their non-generic counterparts.
Type parameters are declared in square brackets ([]
) immediately
after the name of the function, class, or type alias. The type parameters
are accessible within the scope of the generic object, but not elsewhere.
Thus, after a declaration def func[T](): pass
, the name T
is not available in
the module scope. Below, the semantics of generic objects are described
with more precision. The scope of type parameters is modeled with a special
function (technically, an annotation scope) that
wraps the creation of the generic object.
Generic functions, classes, and type aliases have a
__type_params__
attribute listing their type parameters.
Type parameters come in three kinds:
typing.TypeVar
, introduced by a plain name (e.g.,T
). Semantically, this represents a single type to a type checker.typing.TypeVarTuple
, introduced by a name prefixed with a single asterisk (e.g.,*Ts
). Semantically, this stands for a tuple of any number of types.typing.ParamSpec
, introduced by a name prefixed with two asterisks (e.g.,**P
). Semantically, this stands for the parameters of a callable.
typing.TypeVar
declarations can define bounds and constraints with
a colon (:
) followed by an expression. A single expression after the colon
indicates a bound (e.g. T: int
). Semantically, this means
that the typing.TypeVar
can only represent types that are a subtype of
this bound. A parenthesized tuple of expressions after the colon indicates a
set of constraints (e.g. T: (str, bytes)
). Each member of the tuple should be a
type (again, this is not enforced at runtime). Constrained type variables can only
take on one of the types in the list of constraints.
For typing.TypeVar
s declared using the type parameter list syntax,
the bound and constraints are not evaluated when the generic object is created,
but only when the value is explicitly accessed through the attributes __bound__
and __constraints__
. To accomplish this, the bounds or constraints are
evaluated in a separate annotation scope.
typing.TypeVarTuple
s and typing.ParamSpec
s cannot have bounds
or constraints.
All three flavors of type parameters can also have a default value, which is used
when the type parameter is not explicitly provided. This is added by appending
a single equals sign (=
) followed by an expression. Like the bounds and
constraints of type variables, the default value is not evaluated when the
object is created, but only when the type parameter’s __default__
attribute
is accessed. To this end, the default value is evaluated in a separate
annotation scope. If no default value is specified
for a type parameter, the __default__
attribute is set to the special
sentinel object typing.NoDefault
.
The following example indicates the full set of allowed type parameter declarations:
def overly_generic[
SimpleTypeVar,
TypeVarWithDefault = int,
TypeVarWithBound: int,
TypeVarWithConstraints: (str, bytes),
*SimpleTypeVarTuple = (int, float),
**SimpleParamSpec = (str, bytearray),
](
a: SimpleTypeVar,
b: TypeVarWithDefault,
c: TypeVarWithBound,
d: Callable[SimpleParamSpec, TypeVarWithConstraints],
*e: SimpleTypeVarTuple,
): ...
8.10.1. Generic functions¶
Generic functions are declared as follows:
def func[T](arg: T): ...
This syntax is equivalent to:
annotation-def TYPE_PARAMS_OF_func():
T = typing.TypeVar("T")
def func(arg: T): ...
func.__type_params__ = (T,)
return func
func = TYPE_PARAMS_OF_func()
Here annotation-def
indicates an annotation scope,
which is not actually bound to any name at runtime. (One
other liberty is taken in the translation: the syntax does not go through
attribute access on the typing
module, but creates an instance of
typing.TypeVar
directly.)
The annotations of generic functions are evaluated within the annotation scope used for declaring the type parameters, but the function’s defaults and decorators are not.
The following example illustrates the scoping rules for these cases, as well as for additional flavors of type parameters:
@decorator
def func[T: int, *Ts, **P](*args: *Ts, arg: Callable[P, T] = some_default):
...
Except for the lazy evaluation of the
TypeVar
bound, this is equivalent to:
DEFAULT_OF_arg = some_default
annotation-def TYPE_PARAMS_OF_func():
annotation-def BOUND_OF_T():
return int
# In reality, BOUND_OF_T() is evaluated only on demand.
T = typing.TypeVar("T", bound=BOUND_OF_T())
Ts = typing.TypeVarTuple("Ts")
P = typing.ParamSpec("P")
def func(*args: *Ts, arg: Callable[P, T] = DEFAULT_OF_arg):
...
func.__type_params__ = (T, Ts, P)
return func
func = decorator(TYPE_PARAMS_OF_func())
The capitalized names like DEFAULT_OF_arg
are not actually
bound at runtime.
8.10.2. Generic classes¶
Generic classes are declared as follows:
class Bag[T]: ...
This syntax is equivalent to:
annotation-def TYPE_PARAMS_OF_Bag():
T = typing.TypeVar("T")
class Bag(typing.Generic[T]):
__type_params__ = (T,)
...
return Bag
Bag = TYPE_PARAMS_OF_Bag()
Here again annotation-def
(not a real keyword) indicates an
annotation scope, and the name
TYPE_PARAMS_OF_Bag
is not actually bound at runtime.
Generic classes implicitly inherit from typing.Generic
.
The base classes and keyword arguments of generic classes are
evaluated within the type scope for the type parameters,
and decorators are evaluated outside that scope. This is illustrated
by this example:
@decorator
class Bag(Base[T], arg=T): ...
This is equivalent to:
annotation-def TYPE_PARAMS_OF_Bag():
T = typing.TypeVar("T")
class Bag(Base[T], typing.Generic[T], arg=T):
__type_params__ = (T,)
...
return Bag
Bag = decorator(TYPE_PARAMS_OF_Bag())
8.10.3. Generic type aliases¶
The type
statement can also be used to create a generic type alias:
type ListOrSet[T] = list[T] | set[T]
Except for the lazy evaluation of the value, this is equivalent to:
annotation-def TYPE_PARAMS_OF_ListOrSet():
T = typing.TypeVar("T")
annotation-def VALUE_OF_ListOrSet():
return list[T] | set[T]
# In reality, the value is lazily evaluated
return typing.TypeAliasType("ListOrSet", VALUE_OF_ListOrSet(), type_params=(T,))
ListOrSet = TYPE_PARAMS_OF_ListOrSet()
Here, annotation-def
(not a real keyword) indicates an
annotation scope. The capitalized names
like TYPE_PARAMS_OF_ListOrSet
are not actually bound at runtime.
8.11. Annotations¶
Changed in version 3.14: Annotations are now lazily evaluated by default.
Variables and function parameters may carry annotations, created by adding a colon after the name, followed by an expression:
x: annotation = 1
def f(param: annotation): ...
Functions may also carry a return annotation following an arrow:
def f() -> annotation: ...
Annotations are conventionally used for type hints, but this
is not enforced by the language, and in general annotations may contain arbitrary
expressions. The presence of annotations does not change the runtime semantics of
the code, except if some mechanism is used that introspects and uses the annotations
(such as dataclasses
or functools.singledispatch()
).
By default, annotations are lazily evaluated in an annotation scope.
This means that they are not evaluated when the code containing the annotation is evaluated.
Instead, the interpreter saves information that can be used to evaluate the annotation later
if requested. The annotationlib
module provides tools for evaluating annotations.
If the future statement from __future__ import annotations
is present,
all annotations are instead stored as strings:
>>> from __future__ import annotations
>>> def f(param: annotation): ...
>>> f.__annotations__
{'param': 'annotation'}
This future statement will be deprecated and removed in a future version of Python,
but not before Python 3.13 reaches its end of life (see PEP 749).
When it is used, introspection tools like
annotationlib.get_annotations()
and typing.get_type_hints()
are
less likely to be able to resolve annotations at runtime.
Footnotes


Command line and environment

1. Command line and environment¶
The CPython interpreter scans the command line and the environment for various settings.
CPython implementation detail: Other implementations’ command line schemes may differ. See Alternate Implementations for further resources.
1.1. Command line¶
When invoking Python, you may specify any of these options:
python [-bBdEhiIOPqRsSuvVWx?] [-c command | -m module-name | script | - ] [args]
The most common use case is, of course, a simple invocation of a script:
python myscript.py
1.1.1. Interface options¶
The interpreter interface resembles that of the UNIX shell, but provides some additional methods of invocation:
When called with standard input connected to a tty device, it prompts for commands and executes them until an EOF (an end-of-file character, you can produce that with Ctrl-D on UNIX or Ctrl-Z, Enter on Windows) is read. For more on interactive mode, see Interactive Mode.
When called with a file name argument or with a file as standard input, it reads and executes a script from that file.
When called with a directory name argument, it reads and executes an appropriately named script from that directory.
When called with
-c command
, it executes the Python statement(s) given as command. Here command may contain multiple statements separated by newlines. Leading whitespace is significant in Python statements!When called with
-m module-name
, the given module is located on the Python module path and executed as a script.
In non-interactive mode, the entire input is parsed before it is executed.
An interface option terminates the list of options consumed by the interpreter,
all consecutive arguments will end up in sys.argv
– note that the first
element, subscript zero (sys.argv[0]
), is a string reflecting the program’s
source.
- -c <command>¶
Execute the Python code in command. command can be one or more statements separated by newlines, with significant leading whitespace as in normal module code.
If this option is given, the first element of
sys.argv
will be"-c"
and the current directory will be added to the start ofsys.path
(allowing modules in that directory to be imported as top level modules).Raises an auditing event
cpython.run_command
with argumentcommand
.Changed in version 3.14: command is automatically dedented before execution.
- -m <module-name>¶
Search
sys.path
for the named module and execute its contents as the__main__
module.Since the argument is a module name, you must not give a file extension (
.py
). The module name should be a valid absolute Python module name, but the implementation may not always enforce this (e.g. it may allow you to use a name that includes a hyphen).Package names (including namespace packages) are also permitted. When a package name is supplied instead of a normal module, the interpreter will execute
<pkg>.__main__
as the main module. This behaviour is deliberately similar to the handling of directories and zipfiles that are passed to the interpreter as the script argument.Note
This option cannot be used with built-in modules and extension modules written in C, since they do not have Python module files. However, it can still be used for precompiled modules, even if the original source file is not available.
If this option is given, the first element of
sys.argv
will be the full path to the module file (while the module file is being located, the first element will be set to"-m"
). As with the-c
option, the current directory will be added to the start ofsys.path
.-I
option can be used to run the script in isolated mode wheresys.path
contains neither the current directory nor the user’s site-packages directory. AllPYTHON*
environment variables are ignored, too.Many standard library modules contain code that is invoked on their execution as a script. An example is the
timeit
module:python -m timeit -s "setup here" "benchmarked code here" python -m timeit -h # for details
Raises an auditing event
cpython.run_module
with argumentmodule-name
.See also
runpy.run_module()
Equivalent functionality directly available to Python code
PEP 338 – Executing modules as scripts
Changed in version 3.1: Supply the package name to run a
__main__
submodule.Changed in version 3.4: namespace packages are also supported
- -
Read commands from standard input (
sys.stdin
). If standard input is a terminal,-i
is implied.If this option is given, the first element of
sys.argv
will be"-"
and the current directory will be added to the start ofsys.path
.Raises an auditing event
cpython.run_stdin
with no arguments.
- <script>
Execute the Python code contained in script, which must be a filesystem path (absolute or relative) referring to either a Python file, a directory containing a
__main__.py
file, or a zipfile containing a__main__.py
file.If this option is given, the first element of
sys.argv
will be the script name as given on the command line.If the script name refers directly to a Python file, the directory containing that file is added to the start of
sys.path
, and the file is executed as the__main__
module.If the script name refers to a directory or zipfile, the script name is added to the start of
sys.path
and the__main__.py
file in that location is executed as the__main__
module.-I
option can be used to run the script in isolated mode wheresys.path
contains neither the script’s directory nor the user’s site-packages directory. AllPYTHON*
environment variables are ignored, too.Raises an auditing event
cpython.run_file
with argumentfilename
.See also
runpy.run_path()
Equivalent functionality directly available to Python code
If no interface option is given, -i
is implied, sys.argv[0]
is
an empty string (""
) and the current directory will be added to the
start of sys.path
. Also, tab-completion and history editing is
automatically enabled, if available on your platform (see
Readline configuration).
See also
Changed in version 3.4: Automatic enabling of tab-completion and history editing.
1.1.2. Generic options¶
- -?¶
- -h¶
- --help¶
Print a short description of all command line options and corresponding environment variables and exit.
- --help-env¶
Print a short description of Python-specific environment variables and exit.
Added in version 3.11.
- --help-xoptions¶
Print a description of implementation-specific
-X
options and exit.Added in version 3.11.
- --help-all¶
Print complete usage information and exit.
Added in version 3.11.
1.1.3. Miscellaneous options¶
- -b¶
Issue a warning when converting
bytes
orbytearray
tostr
without specifying encoding or comparingbytes
orbytearray
withstr
orbytes
withint
. Issue an error when the option is given twice (-bb
).
- -B¶
If given, Python won’t try to write
.pyc
files on the import of source modules. See alsoPYTHONDONTWRITEBYTECODE
.
- --check-hash-based-pycs default|always|never¶
Control the validation behavior of hash-based
.pyc
files. See Cached bytecode invalidation. When set todefault
, checked and unchecked hash-based bytecode cache files are validated according to their default semantics. When set toalways
, all hash-based.pyc
files, whether checked or unchecked, are validated against their corresponding source file. When set tonever
, hash-based.pyc
files are not validated against their corresponding source files.The semantics of timestamp-based
.pyc
files are unaffected by this option.
- -d¶
Turn on parser debugging output (for expert only). See also the
PYTHONDEBUG
environment variable.This option requires a debug build of Python, otherwise it’s ignored.
- -E¶
Ignore all
PYTHON*
environment variables, e.g.PYTHONPATH
andPYTHONHOME
, that might be set.
- -i¶
Enter interactive mode after execution.
Using the
-i
option will enter interactive mode in any of the following circumstances:Interactive mode will start even when
sys.stdin
does not appear to be a terminal. ThePYTHONSTARTUP
file is not read.This can be useful to inspect global variables or a stack trace when a script raises an exception. See also
PYTHONINSPECT
.
- -I¶
Run Python in isolated mode. This also implies
-E
,-P
and-s
options.In isolated mode
sys.path
contains neither the script’s directory nor the user’s site-packages directory. AllPYTHON*
environment variables are ignored, too. Further restrictions may be imposed to prevent the user from injecting malicious code.Added in version 3.4.
- -O¶
Remove assert statements and any code conditional on the value of
__debug__
. Augment the filename for compiled (bytecode) files by adding.opt-1
before the.pyc
extension (see PEP 488). See alsoPYTHONOPTIMIZE
.Changed in version 3.5: Modify
.pyc
filenames according to PEP 488.
- -OO¶
Do
-O
and also discard docstrings. Augment the filename for compiled (bytecode) files by adding.opt-2
before the.pyc
extension (see PEP 488).Changed in version 3.5: Modify
.pyc
filenames according to PEP 488.
- -P¶
Don’t prepend a potentially unsafe path to
sys.path
:python -m module
command line: Don’t prepend the current working directory.python script.py
command line: Don’t prepend the script’s directory. If it’s a symbolic link, resolve symbolic links.python -c code
andpython
(REPL) command lines: Don’t prepend an empty string, which means the current working directory.
See also the
PYTHONSAFEPATH
environment variable, and-E
and-I
(isolated) options.Added in version 3.11.
- -q¶
Don’t display the copyright and version messages even in interactive mode.
Added in version 3.2.
- -R¶
Turn on hash randomization. This option only has an effect if the
PYTHONHASHSEED
environment variable is set to anything other thanrandom
, since hash randomization is enabled by default.On previous versions of Python, this option turns on hash randomization, so that the
__hash__()
values of str and bytes objects are “salted” with an unpredictable random value. Although they remain constant within an individual Python process, they are not predictable between repeated invocations of Python.Hash randomization is intended to provide protection against a denial-of-service caused by carefully chosen inputs that exploit the worst case performance of a dict construction, O(n2) complexity. See http://ocert.org/advisories/ocert-2011-003.html for details.
PYTHONHASHSEED
allows you to set a fixed value for the hash seed secret.Added in version 3.2.3.
Changed in version 3.7: The option is no longer ignored.
- -s¶
Don’t add the
user site-packages directory
tosys.path
.See also
PYTHONNOUSERSITE
.See also
PEP 370 – Per user site-packages directory
- -S¶
Disable the import of the module
site
and the site-dependent manipulations ofsys.path
that it entails. Also disable these manipulations ifsite
is explicitly imported later (callsite.main()
if you want them to be triggered).
- -u¶
Force the stdout and stderr streams to be unbuffered. This option has no effect on the stdin stream.
See also
PYTHONUNBUFFERED
.Changed in version 3.7: The text layer of the stdout and stderr streams now is unbuffered.
- -v¶
Print a message each time a module is initialized, showing the place (filename or built-in module) from which it is loaded. When given twice (
-vv
), print a message for each file that is checked for when searching for a module. Also provides information on module cleanup at exit.Changed in version 3.10: The
site
module reports the site-specific paths and.pth
files being processed.See also
PYTHONVERBOSE
.
- -W arg¶
Warning control. Python’s warning machinery by default prints warning messages to
sys.stderr
.The simplest settings apply a particular action unconditionally to all warnings emitted by a process (even those that are otherwise ignored by default):
-Wdefault # Warn once per call location -Werror # Convert to exceptions -Walways # Warn every time -Wall # Same as -Walways -Wmodule # Warn once per calling module -Wonce # Warn once per Python process -Wignore # Never warn
The action names can be abbreviated as desired and the interpreter will resolve them to the appropriate action name. For example,
-Wi
is the same as-Wignore
.The full form of argument is:
action:message:category:module:lineno
Empty fields match all values; trailing empty fields may be omitted. For example
-W ignore::DeprecationWarning
ignores all DeprecationWarning warnings.The action field is as explained above but only applies to warnings that match the remaining fields.
The message field must match the whole warning message; this match is case-insensitive.
The category field matches the warning category (ex:
DeprecationWarning
). This must be a class name; the match test whether the actual warning category of the message is a subclass of the specified warning category.The module field matches the (fully qualified) module name; this match is case-sensitive.
The lineno field matches the line number, where zero matches all line numbers and is thus equivalent to an omitted line number.
Multiple
-W
options can be given; when a warning matches more than one option, the action for the last matching option is performed. Invalid-W
options are ignored (though, a warning message is printed about invalid options when the first warning is issued).Warnings can also be controlled using the
PYTHONWARNINGS
environment variable and from within a Python program using thewarnings
module. For example, thewarnings.filterwarnings()
function can be used to use a regular expression on the warning message.See The Warnings Filter and Describing Warning Filters for more details.
- -x¶
Skip the first line of the source, allowing use of non-Unix forms of
#!cmd
. This is intended for a DOS specific hack only.
- -X¶
Reserved for various implementation-specific options. CPython currently defines the following possible values:
-X faulthandler
to enablefaulthandler
. See alsoPYTHONFAULTHANDLER
.Added in version 3.3.
-X showrefcount
to output the total reference count and number of used memory blocks when the program finishes or after each statement in the interactive interpreter. This only works on debug builds.Added in version 3.4.
-X tracemalloc
to start tracing Python memory allocations using thetracemalloc
module. By default, only the most recent frame is stored in a traceback of a trace. Use-X tracemalloc=NFRAME
to start tracing with a traceback limit of NFRAME frames. Seetracemalloc.start()
andPYTHONTRACEMALLOC
for more information.Added in version 3.4.
-X int_max_str_digits
configures the integer string conversion length limitation. See alsoPYTHONINTMAXSTRDIGITS
.Added in version 3.11.
-X importtime
to show how long each import takes. It shows module name, cumulative time (including nested imports) and self time (excluding nested imports). Note that its output may be broken in multi-threaded application. Typical usage ispython -X importtime -c 'import asyncio'
.-X importtime=2
enables additional output that indicates when an imported module has already been loaded. In such cases, the stringcached
will be printed in both time columns.See also
PYTHONPROFILEIMPORTTIME
.Added in version 3.7.
Changed in version 3.14: Added
-X importtime=2
to also trace imports of loaded modules, and reserved values other than1
and2
for future use.-X dev
: enable Python Development Mode, introducing additional runtime checks that are too expensive to be enabled by default. See alsoPYTHONDEVMODE
.Added in version 3.7.
-X utf8
enables the Python UTF-8 Mode.-X utf8=0
explicitly disables Python UTF-8 Mode (even when it would otherwise activate automatically). See alsoPYTHONUTF8
.Added in version 3.7.
-X pycache_prefix=PATH
enables writing.pyc
files to a parallel tree rooted at the given directory instead of to the code tree. See alsoPYTHONPYCACHEPREFIX
.Added in version 3.8.
-X warn_default_encoding
issues aEncodingWarning
when the locale-specific default encoding is used for opening files. See alsoPYTHONWARNDEFAULTENCODING
.Added in version 3.10.
-X no_debug_ranges
disables the inclusion of the tables mapping extra location information (end line, start column offset and end column offset) to every instruction in code objects. This is useful when smaller code objects and pyc files are desired as well as suppressing the extra visual location indicators when the interpreter displays tracebacks. See alsoPYTHONNODEBUGRANGES
.Added in version 3.11.
-X frozen_modules
determines whether or not frozen modules are ignored by the import machinery. A value ofon
means they get imported andoff
means they are ignored. The default ison
if this is an installed Python (the normal case). If it’s under development (running from the source tree) then the default isoff
. Note that theimportlib_bootstrap
andimportlib_bootstrap_external
frozen modules are always used, even if this flag is set tooff
. See alsoPYTHON_FROZEN_MODULES
.Added in version 3.11.
-X perf
enables support for the Linuxperf
profiler. When this option is provided, theperf
profiler will be able to report Python calls. This option is only available on some platforms and will do nothing if is not supported on the current system. The default value is “off”. See alsoPYTHONPERFSUPPORT
and Python support for the Linux perf profiler.Added in version 3.12.
-X perf_jit
enables support for the Linuxperf
profiler with DWARF support. When this option is provided, theperf
profiler will be able to report Python calls using DWARF information. This option is only available on some platforms and will do nothing if is not supported on the current system. The default value is “off”. See alsoPYTHON_PERF_JIT_SUPPORT
and Python support for the Linux perf profiler.Added in version 3.13.
-X disable_remote_debug
disables the remote debugging support as described in PEP 768. This includes both the functionality to schedule code for execution in another process and the functionality to receive code for execution in the current process.This option is only available on some platforms and will do nothing if is not supported on the current system. See also
PYTHON_DISABLE_REMOTE_DEBUG
and PEP 768.Added in version 3.14.
-X cpu_count=n
overridesos.cpu_count()
,os.process_cpu_count()
, andmultiprocessing.cpu_count()
. n must be greater than or equal to 1. This option may be useful for users who need to limit CPU resources of a container system. See alsoPYTHON_CPU_COUNT
. If n isdefault
, nothing is overridden.Added in version 3.13.
-X presite=package.module
specifies a module that should be imported before thesite
module is executed and before the__main__
module exists. Therefore, the imported module isn’t__main__
. This can be used to execute code early during Python initialization. Python needs to be built in debug mode for this option to exist. See alsoPYTHON_PRESITE
.Added in version 3.13.
-X gil=0,1
forces the GIL to be disabled or enabled, respectively. Setting to0
is only available in builds configured with--disable-gil
. See alsoPYTHON_GIL
and Free-threaded CPython.Added in version 3.13.
-X thread_inherit_context=0,1
causesThread
to, by default, use a copy of context of the caller ofThread.start()
when starting. Otherwise, threads will start with an empty context. If unset, the value of this option defaults to1
on free-threaded builds and to0
otherwise. See alsoPYTHON_THREAD_INHERIT_CONTEXT
.Added in version 3.14.
-X context_aware_warnings=0,1
causes thewarnings.catch_warnings
context manager to use aContextVar
to store warnings filter state. If unset, the value of this option defaults to1
on free-threaded builds and to0
otherwise. See alsoPYTHON_CONTEXT_AWARE_WARNINGS
.Added in version 3.14.
-X tlbc=0,1
enables (1, the default) or disables (0) thread-local bytecode in builds configured with--disable-gil
. When disabled, this also disables the specializing interpreter. See alsoPYTHON_TLBC
.Added in version 3.14.
It also allows passing arbitrary values and retrieving them through the
sys._xoptions
dictionary.Added in version 3.2.
Changed in version 3.9: Removed the
-X showalloccount
option.Changed in version 3.10: Removed the
-X oldparser
option.
Removed in version 3.14: -J
is no longer reserved for use by Jython,
and now has no special meaning.
1.1.4. Controlling color¶
The Python interpreter is configured by default to use colors to highlight output in certain situations such as when displaying tracebacks. This behavior can be controlled by setting different environment variables.
Setting the environment variable TERM
to dumb
will disable color.
If the FORCE_COLOR
environment variable is set, then color will be
enabled regardless of the value of TERM. This is useful on CI systems which
aren’t terminals but can still display ANSI escape sequences.
If the NO_COLOR
environment variable is set, Python will disable all color
in the output. This takes precedence over FORCE_COLOR
.
All these environment variables are used also by other tools to control color
output. To control the color output only in the Python interpreter, the
PYTHON_COLORS
environment variable can be used. This variable takes
precedence over NO_COLOR
, which in turn takes precedence over
FORCE_COLOR
.
1.2. Environment variables¶
These environment variables influence Python’s behavior, they are processed before the command-line switches other than -E or -I. It is customary that command-line switches override environmental variables where there is a conflict.
- PYTHONHOME¶
Change the location of the standard Python libraries. By default, the libraries are searched in
prefix/lib/pythonversion
andexec_prefix/lib/pythonversion
, whereprefix
andexec_prefix
are installation-dependent directories, both defaulting to/usr/local
.When
PYTHONHOME
is set to a single directory, its value replaces bothprefix
andexec_prefix
. To specify different values for these, setPYTHONHOME
toprefix:exec_prefix
.
- PYTHONPATH¶
Augment the default search path for module files. The format is the same as the shell’s
PATH
: one or more directory pathnames separated byos.pathsep
(e.g. colons on Unix or semicolons on Windows). Non-existent directories are silently ignored.In addition to normal directories, individual
PYTHONPATH
entries may refer to zipfiles containing pure Python modules (in either source or compiled form). Extension modules cannot be imported from zipfiles.The default search path is installation dependent, but generally begins with
prefix/lib/pythonversion
(seePYTHONHOME
above). It is always appended toPYTHONPATH
.An additional directory will be inserted in the search path in front of
PYTHONPATH
as described above under Interface options. The search path can be manipulated from within a Python program as the variablesys.path
.
- PYTHONSAFEPATH¶
If this is set to a non-empty string, don’t prepend a potentially unsafe path to
sys.path
: see the-P
option for details.Added in version 3.11.
- PYTHONPLATLIBDIR¶
If this is set to a non-empty string, it overrides the
sys.platlibdir
value.Added in version 3.9.
- PYTHONSTARTUP¶
If this is the name of a readable file, the Python commands in that file are executed before the first prompt is displayed in interactive mode. The file is executed in the same namespace where interactive commands are executed so that objects defined or imported in it can be used without qualification in the interactive session. You can also change the prompts
sys.ps1
andsys.ps2
and the hooksys.__interactivehook__
in this file.Raises an auditing event
cpython.run_startup
with the filename as the argument when called on startup.
- PYTHONOPTIMIZE¶
If this is set to a non-empty string it is equivalent to specifying the
-O
option. If set to an integer, it is equivalent to specifying-O
multiple times.
- PYTHONBREAKPOINT¶
If this is set, it names a callable using dotted-path notation. The module containing the callable will be imported and then the callable will be run by the default implementation of
sys.breakpointhook()
which itself is called by built-inbreakpoint()
. If not set, or set to the empty string, it is equivalent to the value “pdb.set_trace”. Setting this to the string “0” causes the default implementation ofsys.breakpointhook()
to do nothing but return immediately.Added in version 3.7.
- PYTHONDEBUG¶
If this is set to a non-empty string it is equivalent to specifying the
-d
option. If set to an integer, it is equivalent to specifying-d
multiple times.This environment variable requires a debug build of Python, otherwise it’s ignored.
- PYTHONINSPECT¶
If this is set to a non-empty string it is equivalent to specifying the
-i
option.This variable can also be modified by Python code using
os.environ
to force inspect mode on program termination.Raises an auditing event
cpython.run_stdin
with no arguments.Changed in version 3.12.5: (also 3.11.10, 3.10.15, 3.9.20, and 3.8.20) Emits audit events.
Changed in version 3.13: Uses PyREPL if possible, in which case
PYTHONSTARTUP
is also executed. Emits audit events.
- PYTHONUNBUFFERED¶
If this is set to a non-empty string it is equivalent to specifying the
-u
option.
- PYTHONVERBOSE¶
If this is set to a non-empty string it is equivalent to specifying the
-v
option. If set to an integer, it is equivalent to specifying-v
multiple times.
- PYTHONCASEOK¶
If this is set, Python ignores case in
import
statements. This only works on Windows and macOS.
- PYTHONDONTWRITEBYTECODE¶
If this is set to a non-empty string, Python won’t try to write
.pyc
files on the import of source modules. This is equivalent to specifying the-B
option.
- PYTHONPYCACHEPREFIX¶
If this is set, Python will write
.pyc
files in a mirror directory tree at this path, instead of in__pycache__
directories within the source tree. This is equivalent to specifying the-X
pycache_prefix=PATH
option.Added in version 3.8.
- PYTHONHASHSEED¶
If this variable is not set or set to
random
, a random value is used to seed the hashes of str and bytes objects.If
PYTHONHASHSEED
is set to an integer value, it is used as a fixed seed for generating the hash() of the types covered by the hash randomization.Its purpose is to allow repeatable hashing, such as for selftests for the interpreter itself, or to allow a cluster of python processes to share hash values.
The integer must be a decimal number in the range [0,4294967295]. Specifying the value 0 will disable hash randomization.
Added in version 3.2.3.
- PYTHONINTMAXSTRDIGITS¶
If this variable is set to an integer, it is used to configure the interpreter’s global integer string conversion length limitation.
Added in version 3.11.
- PYTHONIOENCODING¶
If this is set before running the interpreter, it overrides the encoding used for stdin/stdout/stderr, in the syntax
encodingname:errorhandler
. Both theencodingname
and the:errorhandler
parts are optional and have the same meaning as instr.encode()
.For stderr, the
:errorhandler
part is ignored; the handler will always be'backslashreplace'
.Changed in version 3.4: The
encodingname
part is now optional.Changed in version 3.6: On Windows, the encoding specified by this variable is ignored for interactive console buffers unless
PYTHONLEGACYWINDOWSSTDIO
is also specified. Files and pipes redirected through the standard streams are not affected.
- PYTHONNOUSERSITE¶
If this is set, Python won’t add the
user site-packages directory
tosys.path
.See also
PEP 370 – Per user site-packages directory
- PYTHONUSERBASE¶
Defines the
user base directory
, which is used to compute the path of theuser site-packages directory
and installation paths forpython -m pip install --user
.See also
PEP 370 – Per user site-packages directory
- PYTHONEXECUTABLE¶
If this environment variable is set,
sys.argv[0]
will be set to its value instead of the value got through the C runtime. Only works on macOS.
- PYTHONWARNINGS¶
This is equivalent to the
-W
option. If set to a comma separated string, it is equivalent to specifying-W
multiple times, with filters later in the list taking precedence over those earlier in the list.The simplest settings apply a particular action unconditionally to all warnings emitted by a process (even those that are otherwise ignored by default):
PYTHONWARNINGS=default # Warn once per call location PYTHONWARNINGS=error # Convert to exceptions PYTHONWARNINGS=always # Warn every time PYTHONWARNINGS=all # Same as PYTHONWARNINGS=always PYTHONWARNINGS=module # Warn once per calling module PYTHONWARNINGS=once # Warn once per Python process PYTHONWARNINGS=ignore # Never warn
See The Warnings Filter and Describing Warning Filters for more details.
- PYTHONFAULTHANDLER¶
If this environment variable is set to a non-empty string,
faulthandler.enable()
is called at startup: install a handler forSIGSEGV
,SIGFPE
,SIGABRT
,SIGBUS
andSIGILL
signals to dump the Python traceback. This is equivalent to-X
faulthandler
option.Added in version 3.3.
- PYTHONTRACEMALLOC¶
If this environment variable is set to a non-empty string, start tracing Python memory allocations using the
tracemalloc
module. The value of the variable is the maximum number of frames stored in a traceback of a trace. For example,PYTHONTRACEMALLOC=1
stores only the most recent frame. See thetracemalloc.start()
function for more information. This is equivalent to setting the-X
tracemalloc
option.Added in version 3.4.
- PYTHONPROFILEIMPORTTIME¶
If this environment variable is set to
1
, Python will show how long each import takes. If set to2
, Python will include output for imported modules that have already been loaded. This is equivalent to setting the-X
importtime
option.Added in version 3.7.
Changed in version 3.14: Added
PYTHONPROFILEIMPORTTIME=2
to also trace imports of loaded modules.
- PYTHONASYNCIODEBUG¶
If this environment variable is set to a non-empty string, enable the debug mode of the
asyncio
module.Added in version 3.4.
- PYTHONMALLOC¶
Set the Python memory allocators and/or install debug hooks.
Set the family of memory allocators used by Python:
default
: use the default memory allocators.malloc
: use themalloc()
function of the C library for all domains (PYMEM_DOMAIN_RAW
,PYMEM_DOMAIN_MEM
,PYMEM_DOMAIN_OBJ
).pymalloc
: use the pymalloc allocator forPYMEM_DOMAIN_MEM
andPYMEM_DOMAIN_OBJ
domains and use themalloc()
function for thePYMEM_DOMAIN_RAW
domain.mimalloc
: use the mimalloc allocator forPYMEM_DOMAIN_MEM
andPYMEM_DOMAIN_OBJ
domains and use themalloc()
function for thePYMEM_DOMAIN_RAW
domain.
Install debug hooks:
debug
: install debug hooks on top of the default memory allocators.malloc_debug
: same asmalloc
but also install debug hooks.pymalloc_debug
: same aspymalloc
but also install debug hooks.mimalloc_debug
: same asmimalloc
but also install debug hooks.
Added in version 3.6.
Changed in version 3.7: Added the
"default"
allocator.
- PYTHONMALLOCSTATS¶
If set to a non-empty string, Python will print statistics of the pymalloc memory allocator every time a new pymalloc object arena is created, and on shutdown.
This variable is ignored if the
PYTHONMALLOC
environment variable is used to force themalloc()
allocator of the C library, or if Python is configured withoutpymalloc
support.Changed in version 3.6: This variable can now also be used on Python compiled in release mode. It now has no effect if set to an empty string.
- PYTHONLEGACYWINDOWSFSENCODING¶
If set to a non-empty string, the default filesystem encoding and error handler mode will revert to their pre-3.6 values of ‘mbcs’ and ‘replace’, respectively. Otherwise, the new defaults ‘utf-8’ and ‘surrogatepass’ are used.
This may also be enabled at runtime with
sys._enablelegacywindowsfsencoding()
.Availability: Windows.
Added in version 3.6: See PEP 529 for more details.
- PYTHONLEGACYWINDOWSSTDIO¶
If set to a non-empty string, does not use the new console reader and writer. This means that Unicode characters will be encoded according to the active console code page, rather than using utf-8.
This variable is ignored if the standard streams are redirected (to files or pipes) rather than referring to console buffers.
Availability: Windows.
Added in version 3.6.
- PYTHONCOERCECLOCALE¶
If set to the value
0
, causes the main Python command line application to skip coercing the legacy ASCII-based C and POSIX locales to a more capable UTF-8 based alternative.If this variable is not set (or is set to a value other than
0
), theLC_ALL
locale override environment variable is also not set, and the current locale reported for theLC_CTYPE
category is either the defaultC
locale, or else the explicitly ASCII-basedPOSIX
locale, then the Python CLI will attempt to configure the following locales for theLC_CTYPE
category in the order listed before loading the interpreter runtime:C.UTF-8
C.utf8
UTF-8
If setting one of these locale categories succeeds, then the
LC_CTYPE
environment variable will also be set accordingly in the current process environment before the Python runtime is initialized. This ensures that in addition to being seen by both the interpreter itself and other locale-aware components running in the same process (such as the GNUreadline
library), the updated setting is also seen in subprocesses (regardless of whether or not those processes are running a Python interpreter), as well as in operations that query the environment rather than the current C locale (such as Python’s ownlocale.getdefaultlocale()
).Configuring one of these locales (either explicitly or via the above implicit locale coercion) automatically enables the
surrogateescape
error handler forsys.stdin
andsys.stdout
(sys.stderr
continues to usebackslashreplace
as it does in any other locale). This stream handling behavior can be overridden usingPYTHONIOENCODING
as usual.For debugging purposes, setting
PYTHONCOERCECLOCALE=warn
will cause Python to emit warning messages onstderr
if either the locale coercion activates, or else if a locale that would have triggered coercion is still active when the Python runtime is initialized.Also note that even when locale coercion is disabled, or when it fails to find a suitable target locale,
PYTHONUTF8
will still activate by default in legacy ASCII-based locales. Both features must be disabled in order to force the interpreter to useASCII
instead ofUTF-8
for system interfaces.Availability: Unix.
Added in version 3.7: See PEP 538 for more details.
- PYTHONDEVMODE¶
If this environment variable is set to a non-empty string, enable Python Development Mode, introducing additional runtime checks that are too expensive to be enabled by default. This is equivalent to setting the
-X
dev
option.Added in version 3.7.
- PYTHONUTF8¶
If set to
1
, enable the Python UTF-8 Mode.If set to
0
, disable the Python UTF-8 Mode.Setting any other non-empty string causes an error during interpreter initialisation.
Added in version 3.7.
- PYTHONWARNDEFAULTENCODING¶
If this environment variable is set to a non-empty string, issue a
EncodingWarning
when the locale-specific default encoding is used.See Opt-in EncodingWarning for details.
Added in version 3.10.
- PYTHONNODEBUGRANGES¶
If this variable is set, it disables the inclusion of the tables mapping extra location information (end line, start column offset and end column offset) to every instruction in code objects. This is useful when smaller code objects and pyc files are desired as well as suppressing the extra visual location indicators when the interpreter displays tracebacks.
Added in version 3.11.
- PYTHONPERFSUPPORT¶
If this variable is set to a nonzero value, it enables support for the Linux
perf
profiler so Python calls can be detected by it.If set to
0
, disable Linuxperf
profiler support.See also the
-X perf
command-line option and Python support for the Linux perf profiler.Added in version 3.12.
- PYTHON_PERF_JIT_SUPPORT¶
If this variable is set to a nonzero value, it enables support for the Linux
perf
profiler so Python calls can be detected by it using DWARF information.If set to
0
, disable Linuxperf
profiler support.See also the
-X perf_jit
command-line option and Python support for the Linux perf profiler.Added in version 3.13.
- PYTHON_DISABLE_REMOTE_DEBUG¶
If this variable is set to a non-empty string, it disables the remote debugging feature described in PEP 768. This includes both the functionality to schedule code for execution in another process and the functionality to receive code for execution in the current process.
See also the
-X disable_remote_debug
command-line option.Added in version 3.14.
- PYTHON_CPU_COUNT¶
If this variable is set to a positive integer, it overrides the return values of
os.cpu_count()
andos.process_cpu_count()
.See also the
-X cpu_count
command-line option.Added in version 3.13.
- PYTHON_FROZEN_MODULES¶
If this variable is set to
on
oroff
, it determines whether or not frozen modules are ignored by the import machinery. A value ofon
means they get imported andoff
means they are ignored. The default ison
for non-debug builds (the normal case) andoff
for debug builds. Note that theimportlib_bootstrap
andimportlib_bootstrap_external
frozen modules are always used, even if this flag is set tooff
.See also the
-X frozen_modules
command-line option.Added in version 3.13.
- PYTHON_COLORS¶
If this variable is set to
1
, the interpreter will colorize various kinds of output. Setting it to0
deactivates this behavior. See also Controlling color.Added in version 3.13.
- PYTHON_BASIC_REPL¶
If this variable is set to any value, the interpreter will not attempt to load the Python-based REPL that requires
readline
, and will instead use the traditional parser-based REPL.Added in version 3.13.
- PYTHON_HISTORY¶
This environment variable can be used to set the location of a
.python_history
file (by default, it is.python_history
in the user’s home directory).Added in version 3.13.
- PYTHON_GIL¶
If this variable is set to
1
, the global interpreter lock (GIL) will be forced on. Setting it to0
forces the GIL off (needs Python configured with the--disable-gil
build option).See also the
-X gil
command-line option, which takes precedence over this variable, and Free-threaded CPython.Added in version 3.13.
- PYTHON_THREAD_INHERIT_CONTEXT¶
If this variable is set to
1
thenThread
will, by default, use a copy of context of the caller ofThread.start()
when starting. Otherwise, new threads will start with an empty context. If unset, this variable defaults to1
on free-threaded builds and to0
otherwise. See also-X thread_inherit_context
.Added in version 3.14.
- PYTHON_CONTEXT_AWARE_WARNINGS¶
If set to
1
then thewarnings.catch_warnings
context manager will use aContextVar
to store warnings filter state. If unset, this variable defaults to1
on free-threaded builds and to0
otherwise. See-X context_aware_warnings
.Added in version 3.14.
- PYTHON_JIT¶
On builds where experimental just-in-time compilation is available, this variable can force the JIT to be disabled (
0
) or enabled (1
) at interpreter startup.Added in version 3.13.
- PYTHON_TLBC¶
If set to
1
enables thread-local bytecode. If set to0
thread-local bytecode and the specializing interpreter are disabled. Only applies to builds configured with--disable-gil
.See also the
-X tlbc
command-line option.Added in version 3.14.
1.2.1. Debug-mode variables¶
- PYTHONDUMPREFS¶
If set, Python will dump objects and reference counts still alive after shutting down the interpreter.
Needs Python configured with the
--with-trace-refs
build option.
- PYTHONDUMPREFSFILE¶
If set, Python will dump objects and reference counts still alive after shutting down the interpreter into a file under the path given as the value to this environment variable.
Needs Python configured with the
--with-trace-refs
build option.Added in version 3.11.
- PYTHON_PRESITE¶
If this variable is set to a module, that module will be imported early in the interpreter lifecycle, before the
site
module is executed, and before the__main__
module is created. Therefore, the imported module is not treated as__main__
.This can be used to execute code early during Python initialization.
To import a submodule, use
package.module
as the value, like in an import statement.See also the
-X presite
command-line option, which takes precedence over this variable.Needs Python configured with the
--with-pydebug
build option.Added in version 3.13.


Python Setup and Usage

Python Setup and Usage¶
This part of the documentation is devoted to general information on the setup of the Python environment on different platforms, the invocation of the interpreter and things that make working with Python easier.
- 1. Command line and environment
- 2. Using Python on Unix platforms
- 3. Configure Python
- 4. Using Python on Windows
- 4.1. Python install manager
- 4.2. The embeddable package
- 4.3. The nuget.org packages
- 4.4. Alternative bundles
- 4.5. Supported Windows versions
- 4.6. Removing the MAX_PATH limitation
- 4.7. UTF-8 mode
- 4.8. Finding modules
- 4.9. Additional modules
- 4.10. Compiling Python on Windows
- 4.11. The full installer (deprecated)
- 4.12. Python launcher for Windows (deprecated)
- 5. Using Python on macOS
- 6. Using Python on Android
- 7. Using Python on iOS
- 8. Editors and IDEs