.PY File Format – File structure

Kinds of file

The name of a module comes from its file name, so a file that is meant to be imported needs a name that is also a valid identifier. A script run directly can have any name.

On Windows the import system accepts .pyw as source as well as .py. On other systems only .py is imported as source.

Text and lines

A file holds a sequence of statements. The grammar for a whole file is short (Language Reference 9.2):

file_input: (NEWLINE | statement)* ENDMARKER

The same rule is used for a complete program, for a module, and for a string passed to exec(). An empty file is a valid module.

• Lines may end in LF, CR LF or CR, and a file may mix them. Each is replaced by a single LF, even inside string literals (Language Reference 2.1.2).
• The last line needs no line ending. The end of the file ends it.
• A NUL byte is not allowed anywhere in source and raises SyntaxError.
• Indentation is part of the syntax, so spaces and tabs at the start of a line matter. See Indentation.

Source encoding

Source is UTF-8 unless the file says otherwise (PEP 3120, Python 3.0). Python 2 assumed ASCII. To use another encoding, the file carries an encoding declaration (PEP 263, Language Reference 2.1.4): a comment in the first or second line that matches this regular expression.

coding[=:]\s*([-\w.]+)

The first group names the encoding, and the name must be one Python's codecs know. The usual forms are written for editors, which recognise the same line:

# -*- coding: latin-1 -*-

# vim: set fileencoding=latin-1 :

# coding=latin-1

The rules are strict about where the comment goes:

A declaration covers the whole file, including its comments and string literals. It changes only how the source is decoded. Strings in the running program are always Unicode. Bytes literals may contain only ASCII characters whatever the source encoding is.

The source encoding has nothing to do with the encoding open() uses for data files. That default became UTF-8 in Python 3.15 (PEP 686).

The #! line

On Unix, a script that is marked executable can start with a #! line naming the interpreter. The operating system reads that line when the file is run as a command. To Python it is only a comment, so a file with one runs the same way under python file.py.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""Print a greeting."""

print("Hello, world")

Using /usr/bin/env python3 finds the interpreter through PATH, which also picks up the active virtual environment. A file that has a shebang must have it on line 1 starting at the first byte, so any encoding declaration then goes on line 2.

Windows ignores the line, but the py launcher reads it to choose a Python version (PEP 397, Python 3.3).

Modules

Each source file is one module, and its top-level code is the module body. The body runs once, in order, the first time the module is imported. def and class are statements like any other: they run when they are reached and bind a name to a new object, so there is no separate declaration stage. Code can use a name only after the statement that binds it has run.

Python does not fix the order of the parts of a file, except that a future statement must come before other code. By convention (PEP 8) a module is laid out like this:

#!/usr/bin/env python3
"""Count the words in a file."""

from __future__ import annotations

import sys
from collections import Counter

MAX_WORDS = 20


def count_words(path: str) -> Counter:
    with open(path, encoding="utf-8") as file:
        return Counter(file.read().split())


def main() -> int:
    for word, count in count_words(sys.argv[1]).most_common(MAX_WORDS):
        print(f"{count:6} {word}")
    return 0


if __name__ == "__main__":
    sys.exit(main())

Running a file

A running program has a top-level module whose name is '__main__'. The usual ways of starting Python all create it:

The -P option leaves that first entry off, and -I (isolated mode) implies it. A complete program starts with only sys, builtins and __main__ initialised (Language Reference 9.1).

def main():
    ...

if __name__ == "__main__":
    main()

A package's __main__.py is usually short and imports the real code from elsewhere in the package. Details of how modules are found are on Modules and packages.

.pyi stub files

A stub file gives the types of a module without its code, for example for a module written in C. It uses the same syntax as Python, with ... in place of function bodies, and the extension .pyi lets it sit beside the matching .py file. The interpreter never imports it. Only type checkers and editors read it. The rules are on Type hints.

def greet(name: str, *, loud: bool = ...) -> str: ...

class Greeter:
    prefix: str
    def __init__(self, prefix: str) -> None: ...

How a file becomes a .pyc

In CPython, the reference implementation, source goes through these stages. They are an implementation detail, not part of the language.

1. Decoding. The bytes are decoded to text using the source encoding.
2. Tokenising. The text becomes tokens, including NEWLINE, INDENT and DEDENT. The tokenize module shows them.
3. Parsing. A PEG parser (PEP 617, Python 3.9) builds an abstract syntax tree, which ast.parse exposes.
4. Compiling. A symbol table works out each name's scope, then the tree is compiled to a code object of bytecode, which dis disassembles.
5. Running. The interpreter loop executes the code object.

When a module is imported from source, the code object is also stored in a .pyc file, so the next import can skip compiling. The script named on the command line is compiled but never cached.

The cached files live in a __pycache__ folder beside the source, named with the interpreter's tag so that different versions can share the folder (PEP 3147, Python 3.2):

The tag is sys.implementation.cache_tag. The .opt-N names come from PEP 488 (Python 3.5), which ended the old .pyo files.