# CPython — User Guide

CPython is the reference implementation of the Python programming language. It ships the interpreter, the comprehensive standard library (300+ modules), build tooling, and platform support spanning Windows, macOS, Linux, WebAssembly (Emscripten/WASI), Android, and iOS. Whether you are writing your first script or orchestrating large-scale data pipelines, CPython is the engine underneath.

This guide covers installation, day-to-day usage, every user-facing CLI tool in the standard library, workflows, troubleshooting, and answers to the questions people actually ask.

---

## 1. Quick Start

### 1.1 Get Python Running in 60 Seconds

**On macOS (Homebrew):**

```bash
brew install python@3.13
python3 --version
```

```text
Python 3.13.x
```

**On Ubuntu / Debian:**

```bash
sudo apt update && sudo apt install python3 python3-pip python3-venv
python3 --version
```

```text
Python 3.13.x
```

**On Windows (installer):**

Download from [python.org/downloads](https://www.python.org/downloads/). Check "Add python.exe to PATH" during installation. Then open a terminal:

```bash
python --version
```

```text
Python 3.13.x
```

> [!TIP]
> On Windows, the command is `python` (not `python3`). On macOS and Linux, use `python3` to avoid accidentally invoking a system Python 2. Throughout this guide, `python` means whichever invocation is correct for your platform.

### 1.2 Your First Script

Create `hello.py`:

```python
print("Hello from CPython!")
```

Run it:

```bash
python hello.py
```

```text
Hello from CPython!
```

### 1.3 The Interactive REPL

Launch the REPL for quick experiments:

```bash
python
```

```text
Python 3.13.x (main, ...) [GCC ...] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
```

Type expressions directly:

```python
>>> 2 ** 128
340282366920938463463374607431768211456
>>> import sys; sys.version
'3.13.x (main, ...) [GCC ...]'
```

Exit with `exit()`, `quit()`, or Ctrl-D (Ctrl-Z + Enter on Windows).

> [!TIP]
> The new `pyrepl`-based REPL (default since 3.13) supports multi-line editing, syntax highlighting, and bracket matching. Set `PYTHON_BASIC_REPL=1` to fall back to the classic REPL if you experience compatibility issues with screen readers or automation tools.

### 1.4 Virtual Environments (Do This Every Time)

Never install packages into the system Python. Always use a virtual environment:

```bash
python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows
pip install requests
```

```text
Creating virtual environment...
Successfully installed requests-2.32.x
```

### 1.5 Run a Module Directly

Every standard library tool in this guide uses the `-m` flag:

```bash
python -m json.tool data.json
python -m http.server 8080
python -m unittest discover
```

The `-m` flag tells CPython to locate the named module in `sys.path` and execute it as `__main__`.

---

## 2. Installation

### 2.1 Supported Platforms

| Platform | Architecture | Notes |
|----------|-------------|-------|
| Windows | x86-64, ARM64 | Official installer, Microsoft Store, winget |
| macOS | x86-64, ARM64 (Apple Silicon) | Official installer, Homebrew, MacPorts |
| Linux | x86-64, ARM64, s390x, ppc64le | Distro packages, deadsnakes PPA, build from source |
| WebAssembly | Emscripten, WASI | Experimental; browser and standalone runtimes |
| Android | ARM64, x86-64 | Cross-compilation; experimental |
| iOS | ARM64 | Cross-compilation; experimental |

### 2.2 Windows Installation

#### 2.2.1 Official Installer

1. Download from [python.org/downloads/windows](https://www.python.org/downloads/windows/).
2. Run the `.exe` installer.
3. **Check "Add python.exe to PATH"** at the bottom of the first screen.
4. Click "Install Now" for defaults, or "Customize installation" to control features.

Verify:

```bash
python --version
pip --version
```

```text
Python 3.13.x
pip 24.x from ... (python 3.13)
```

> [!IMPORTANT]
> If you skip "Add python.exe to PATH", you must either use the Windows "py" launcher (`py -3.13`) or manually add `C:\Users\<you>\AppData\Local\Programs\Python\Python313\` and its `Scripts\` subdirectory to your system PATH.

#### 2.2.2 Microsoft Store

```bash
winget install Python.Python.3.13
```

The Store version sandboxes some filesystem access. For development work, prefer the official installer.

#### 2.2.3 Windows py Launcher

Windows ships the `py.exe` launcher that selects Python versions:

```bash
py -3.13 --version
py -3.12 --version
py --list
```

```text
Python 3.13.x
Python 3.12.x
 -V:3.13 *        Python 3.13
 -V:3.12          Python 3.12
```

### 2.3 macOS Installation

#### 2.3.1 Homebrew (Recommended)

```bash
brew install python@3.13
```

Homebrew links `python3` and `pip3` automatically. Verify:

```bash
python3 --version
which python3
```

```text
Python 3.13.x
/opt/homebrew/bin/python3
```

#### 2.3.2 Official Installer

Download the `.pkg` from [python.org/downloads/macos](https://www.python.org/downloads/macos/). After installation, the framework build lives under `/Library/Frameworks/Python.framework/`.

#### 2.3.3 macOS System Python

macOS ships a minimal Python stub that prompts you to install Xcode Command Line Tools. Do not rely on it for development — install your own copy.

### 2.4 Linux Installation

#### 2.4.1 Distribution Packages

**Ubuntu / Debian:**

```bash
sudo apt update
sudo apt install python3 python3-pip python3-venv python3-dev
```

**Fedora:**

```bash
sudo dnf install python3 python3-pip python3-devel
```

**Arch Linux:**

```bash
sudo pacman -S python python-pip
```

#### 2.4.2 deadsnakes PPA (Ubuntu — Multiple Versions)

```bash
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.13 python3.13-venv python3.13-dev
```

#### 2.4.3 pyenv (Any Linux/macOS)

```bash
curl https://pyenv.run | bash
# Follow shell setup instructions, then:
pyenv install 3.13
pyenv global 3.13
python --version
```

```text
Python 3.13.x
```

### 2.5 Building from Source

For contributors or when you need a custom build:

```bash
git clone https://github.com/python/cpython.git
cd cpython
git checkout v3.13.0
```

**Linux / macOS:**

```bash
./configure --prefix=$HOME/.local/python3.13 --enable-optimizations
make -j$(nproc)
make install
```

```text
...
Compiling C modules...
Generating grammar...
Python build finished successfully!
```

**Build dependencies (Debian/Ubuntu):**

```bash
sudo apt install build-essential gdb lcov pkg-config \
  libbz2-dev libffi-dev libgdbm-dev libgdbm-compat-dev liblzma-dev \
  libncurses5-dev libreadline6-dev libsqlite3-dev libssl-dev \
  lzma lzma-dev tk-dev uuid-dev zlib1g-dev
```

> [!WARNING]
> Building without `libssl-dev` produces a Python that cannot use `pip`, `ensurepip`, or any HTTPS connections. Always install OpenSSL development headers before building.

**Windows (from source):**

```bash
PCbuild\build.bat -p x64
```

The build system uses MSBuild and expects Visual Studio 2017 or later.

### 2.6 Verifying Your Installation

```bash
python -c "import sys; print(sys.version); print(sys.platform); print(sys.prefix)"
```

```text
3.13.x (main, ...) [GCC ...]
linux
/usr
```

Check that key modules are available:

```bash
python -c "import ssl; print(ssl.OPENSSL_VERSION)"
python -c "import sqlite3; print(sqlite3.sqlite_version)"
python -c "import tkinter; print(tkinter.TkVersion)"
```

```text
OpenSSL 3.0.x ...
3.45.x
8.6
```

### 2.7 Bootstrap pip with ensurepip

If `pip` is missing from your installation:

```bash
python -m ensurepip --upgrade
```

```text
Looking in links: /tmp/...
Requirement already satisfied: pip in ... (24.x)
```

| Flag | Purpose |
|------|---------|
| `--upgrade` / `-U` | Upgrade pip to the bundled version |
| `--user` | Install into user site-packages |
| `--root DIR` | Install relative to DIR |
| `--altinstall` | Install as `pipX.Y` only (no `pip3`, no `pip`) |
| `--default-pip` | Install as `pip`, `pip3`, and `pipX.Y` |
| `-v` / `--version` | Verbose output / show version |

> [!NOTE]
> Linux distributions that ship `python3-pip` as a separate package sometimes strip `ensurepip`. Install the distro package instead, or use `get-pip.py` from [pip.pypa.io](https://pip.pypa.io/en/stable/installation/).

---

## 3. Configuration

### 3.1 Environment Variables

CPython behavior is controlled through environment variables. These are the ones most relevant to everyday use.

| Variable | Purpose | Example |
|----------|---------|---------|
| `PYTHONSTARTUP` | Script executed on interactive interpreter startup | `export PYTHONSTARTUP=~/.pythonrc` |
| `PYTHONPATH` | Additional directories prepended to `sys.path` | `export PYTHONPATH=/opt/mylibs` |
| `PYTHONUSERBASE` | Base directory for user site-packages (`--user` installs) | `export PYTHONUSERBASE=~/.local` |
| `PYTHONWARNINGS` | Warning filter specifications | `export PYTHONWARNINGS=error::DeprecationWarning` |
| `PYTHONDONTWRITEBYTECODE` | Suppress `.pyc` file creation | `export PYTHONDONTWRITEBYTECODE=1` |
| `PYTHONUNBUFFERED` | Force unbuffered stdout/stderr | `export PYTHONUNBUFFERED=1` |
| `PYTHONHASHSEED` | Fix hash randomization seed (debugging) | `export PYTHONHASHSEED=0` |
| `PYTHONDOCS` | Documentation URL for `pydoc` lookups | `export PYTHONDOCS=https://docs.python.org/3.13` |
| `PYTHONTZPATH` | Timezone data search path (zoneinfo module) | `export PYTHONTZPATH=/usr/share/zoneinfo` |

### 3.2 REPL Configuration

| Variable | Purpose | Example |
|----------|---------|---------|
| `PYTHON_BASIC_REPL` | Force classic REPL (disable pyrepl) | `export PYTHON_BASIC_REPL=1` |
| `PYTHON_BASIC_COMPLETER` | Force basic tab completion in pyrepl | `export PYTHON_BASIC_COMPLETER=1` |
| `PYREPL_TRACE` | Enable tracing for pyrepl debugging | `export PYREPL_TRACE=1` |
| `IDLESTARTUP` | Startup script for IDLE (separate from PYTHONSTARTUP) | `export IDLESTARTUP=~/.idlerc/startup.py` |

### 3.3 Startup File

Create `~/.pythonrc` to customize every interactive session:

```python
# ~/.pythonrc
import readline
import rlcompleter
import atexit
import os

# Tab completion
readline.parse_and_bind("tab: complete")

# History file
histfile = os.path.join(os.path.expanduser("~"), ".python_history")
try:
    readline.read_history_file(histfile)
except FileNotFoundError:
    pass
atexit.register(readline.write_history_file, histfile)

# Handy imports
from pprint import pprint
from datetime import datetime
```

Set the variable:

```bash
export PYTHONSTARTUP=~/.pythonrc
```

Add this to your `.bashrc` / `.zshrc` to make it permanent.

### 3.4 Warning Filters

Control which warnings appear at runtime:

```bash
# Turn DeprecationWarnings into errors
python -W error::DeprecationWarning myscript.py

# Silence all warnings
python -W ignore myscript.py

# Show every warning only once
python -W once myscript.py
```

Or via the environment variable:

```bash
export PYTHONWARNINGS="error::DeprecationWarning,ignore::ResourceWarning"
```

Filter format: `action:message:category:module:lineno`

| Action | Effect |
|--------|--------|
| `error` | Turn warning into an exception |
| `ignore` | Suppress the warning |
| `always` | Always print the warning |
| `default` | Print first occurrence per location |
| `module` | Print first occurrence per module |
| `once` | Print first occurrence anywhere |

### 3.5 Free-Threading (GIL Control)

CPython 3.13+ experimental free-threaded builds expose GIL control:

```bash
export PYTHON_GIL=0   # Disable the GIL (free-threaded build only)
export PYTHON_GIL=1   # Force GIL on (default behavior)
```

> [!IMPORTANT]
> `PYTHON_GIL=0` only works with the free-threaded build of CPython (`python3.13t`). Setting it on a standard build has no effect. The free-threaded build is experimental and not all C extensions are compatible.

### 3.6 Debug and Development Variables

| Variable | Purpose |
|----------|---------|
| `PYTHONASYNCIODEBUG` | Enable asyncio debug mode (slow execution, detailed tracing) |
| `SSLKEYLOGFILE` | Write TLS session keys for Wireshark debugging |
| `SOURCE_DATE_EPOCH` | Unix timestamp for reproducible `.pyc` compilation |
| `POSIXLY_CORRECT` | Strict POSIX behavior in `getopt` |
| `MANPAGER` / `PAGER` | Pager command for `help()` output |

### 3.7 The sysconfig Module

View every build-time configuration variable:

```bash
python -m sysconfig
```

```text
Platform: "linux-x86_64"
Python version: "3.13"
Current installation scheme: "posix_prefix"

Paths:
    data = "/usr"
    include = "/usr/include/python3.13"
    platlib = "/usr/lib/python3.13/site-packages"
    ...

Variables:
    CC = "gcc"
    CFLAGS = "-O2 ..."
    ...
```

This is invaluable when debugging C extension compilation failures.

See Admin Guide for full configuration reference.

---

## 4. Core Usage

### 4.1 Running Python Code

#### 4.1.1 Execute a Script

```bash
python script.py
python script.py arg1 arg2
```

Arguments are available via `sys.argv`:

```python
import sys
print(sys.argv)  # ['script.py', 'arg1', 'arg2']
```

#### 4.1.2 Execute a String

```bash
python -c "print('hello'); import sys; print(sys.version)"
```

#### 4.1.3 Execute a Module

```bash
python -m module_name
```

This finds `module_name` on `sys.path` and runs its `__main__.py` (for packages) or the module itself.

#### 4.1.4 Execute a Directory or ZIP

If a directory or `.zip` file contains `__main__.py`:

```bash
python myproject/
python myapp.zip
```

#### 4.1.5 Read from stdin

```bash
echo "print('piped')" | python
cat script.py | python -
```

### 4.2 Interpreter Flags

| Flag | Purpose |
|------|---------|
| `-B` | Do not write `.pyc` bytecode files |
| `-b` | Warn on `bytes`/`str` comparisons (`-bb` = error) |
| `-c CMD` | Execute CMD as a string |
| `-d` | Parser debugging output |
| `-E` | Ignore all `PYTHON*` environment variables |
| `-i` | Enter interactive mode after running script |
| `-I` | Isolated mode: implies `-E -s`, no user site |
| `-m MOD` | Run library module as a script |
| `-O` | Remove `assert` statements and `__debug__` code |
| `-OO` | `-O` plus remove docstrings |
| `-q` | Quiet mode (suppress version/copyright on startup) |
| `-s` | Do not add user site-packages to `sys.path` |
| `-S` | Do not import `site` on startup |
| `-u` | Unbuffered stdout/stderr |
| `-v` | Verbose import tracing (`-vv` for more) |
| `-W ARG` | Warning control |
| `-x` | Skip the first line of source (for `#!` shebangs) |
| `-X OPT` | Implementation-specific options |

#### Useful `-X` Options

| Option | Purpose |
|--------|---------|
| `-X dev` | Development mode (extra warnings, debug hooks) |
| `-X utf8` | Force UTF-8 mode for I/O |
| `-X faulthandler` | Dump traceback on crash signals |
| `-X tracemalloc` | Trace memory allocations |
| `-X frozen_modules=off` | Use source modules instead of frozen (for debugging) |
| `-X perf` | Enable Linux `perf` profiler support |
| `-X gil=0` | Disable GIL (free-threaded build only) |

### 4.3 The asyncio REPL

The asyncio REPL lets you `await` coroutines directly without boilerplate:

```bash
python -m asyncio
```

```text
asyncio REPL 3.13.x
Use "await" directly instead of "asyncio.run()".
Type "help", "copyright", "credits" or "license" for more information.
>>> import asyncio
>>> await asyncio.sleep(1); print("done")
done
```

#### Task Inspection Subcommands

```bash
python -m asyncio ps         # List running asyncio tasks
python -m asyncio pstree     # Show task tree hierarchy
```

| Flag | Purpose |
|------|---------|
| `--retries N` | Number of connection retries |

> [!NOTE]
> The `ps` and `pstree` subcommands connect to a running asyncio application's monitoring interface. They are diagnostic tools for inspecting task state in production systems.

### 4.4 The Interactive Debugger (pdb)

#### 4.4.1 Launch the Debugger

```bash
python -m pdb script.py
python -m pdb -m mymodule
```

| Flag | Purpose |
|------|---------|
| `-c CMD` / `--command CMD` | Execute debugger command on startup |
| `-m` | Debug a module (like `python -m`) |
| `-p PID` / `--pid PID` | Attach to a running process |

#### 4.4.2 Set Breakpoints in Code

```python
def process(data):
    breakpoint()  # Drops into pdb here
    return data.transform()
```

#### 4.4.3 Essential pdb Commands

| Command | Shortcut | Action |
|---------|----------|--------|
| `next` | `n` | Execute next line (step over) |
| `step` | `s` | Step into function call |
| `continue` | `c` | Continue until next breakpoint |
| `break N` | `b N` | Set breakpoint at line N |
| `list` | `l` | Show source around current line |
| `longlist` | `ll` | Show full function source |
| `print expr` | `p expr` | Evaluate and print expression |
| `pp expr` | | Pretty-print expression |
| `where` | `w` | Print stack trace |
| `up` / `down` | `u` / `d` | Move up/down the call stack |
| `return` | `r` | Continue until function returns |
| `quit` | `q` | Exit debugger |
| `commands N` | | Set commands to run at breakpoint N |
| `display expr` | | Display expression each time execution stops |

#### 4.4.4 Post-Mortem Debugging

```bash
python -m pdb -c continue script.py
```

This runs the script normally; if it crashes, pdb activates at the crash point.

Or from code:

```python
import pdb
try:
    risky_operation()
except Exception:
    pdb.post_mortem()
```

### 4.5 JSON Processing (json.tool)

Pretty-print, validate, and reformat JSON from the command line:

```bash
echo '{"name":"python","version":3.13}' | python -m json.tool
```

```json
{
    "name": "python",
    "version": 3.13
}
```

#### Flag Reference

| Flag | Purpose |
|------|---------|
| `--sort-keys` | Sort object keys alphabetically |
| `--no-ensure-ascii` | Output non-ASCII characters directly (no `\uXXXX` escapes) |
| `--json-lines` | Parse input as JSON Lines (one object per line) |
| `--indent N` | Set indentation level (default: 4) |
| `--tab` | Use tabs for indentation |
| `--no-indent` | Output on a single line |
| `--compact` | Compact output (no spaces after `:` and `,`) |
| `infile` | Input file (default: stdin) |
| `outfile` | Output file (default: stdout) |

#### Examples

**Validate a JSON file:**

```bash
python -m json.tool config.json > /dev/null
```

If invalid, you get a clear error:

```text
Expecting property name enclosed in double quotes: line 3 column 5 (char 42)
```

**Sort keys and compact output:**

```bash
python -m json.tool --sort-keys --compact data.json
```

```text
{"age":30,"city":"NYC","name":"Alice"}
```

**Process JSON Lines (JSONL):**

```bash
python -m json.tool --json-lines events.jsonl
```

Each line is parsed and pretty-printed independently.

**Reformat with tabs:**

```bash
python -m json.tool --tab input.json output.json
```

**Pipe from curl:**

```bash
curl -s https://api.example.com/data | python -m json.tool --sort-keys
```

> [!TIP]
> Use `--no-ensure-ascii` when working with internationalized data. Without it, characters like `ñ` or `日` are escaped to `\u00f1` and `\u65e5`, making the output harder to read.

### 4.6 SQLite CLI (sqlite3)

Interactive SQLite shell built into Python:

```bash
python -m sqlite3 mydb.sqlite3
```

```text
SQLite version 3.45.x
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
sqlite>
```

| Argument | Purpose |
|----------|---------|
| `filename` | Database file to open |
| `sql` | SQL to execute (non-interactive) |
| `-v` / `--version` | Show SQLite version |

**Execute SQL directly:**

```bash
python -m sqlite3 mydb.sqlite3 "SELECT count(*) FROM users;"
```

**Create a database and table:**

```bash
python -m sqlite3 inventory.db "CREATE TABLE items (id INTEGER PRIMARY KEY, name TEXT, qty INTEGER);"
python -m sqlite3 inventory.db "INSERT INTO items VALUES (1, 'Widget', 100);"
python -m sqlite3 inventory.db "SELECT * FROM items;"
```

```text
(1, 'Widget', 100)
```

### 4.7 HTTP Server (http.server)

Serve files from any directory:

```bash
python -m http.server 8080
```

```text
Serving HTTP on 0.0.0.0 port 8080 (http://0.0.0.0:8080/) ...
```

Open `http://localhost:8080` in your browser.

**Bind to a specific address:**

```bash
python -m http.server 8080 --bind 127.0.0.1
```

**Serve a specific directory:**

```bash
python -m http.server 8080 --directory /path/to/docs
```

**HTTPS Server (with TLS):**

```bash
python -m http.server 8443 --certfile cert.pem --keyfile key.pem
```

| Flag | Purpose |
|------|---------|
| `port` | Port number (default: 8000) |
| `--bind ADDRESS` | Bind to specific address |
| `--directory DIR` | Serve files from DIR |
| `--certfile FILE` | TLS certificate for HTTPS |
| `--keyfile FILE` | TLS private key for HTTPS |
| `--protocol VERSION` | HTTP protocol version |

> [!WARNING]
> `http.server` is designed for development and quick file sharing. It has no authentication, no access control, and no hardening. Never expose it to the internet for production use.

### 4.8 Testing (unittest)

#### 4.8.1 Run All Tests

```bash
python -m unittest discover
```

```text
...........
----------------------------------------------------------------------
Ran 11 tests in 0.003s

OK
```

#### 4.8.2 Run Specific Tests

```bash
python -m unittest test_module
python -m unittest test_module.TestClass
python -m unittest test_module.TestClass.test_method
```

#### 4.8.3 Flag Reference

| Flag | Purpose |
|------|---------|
| `-v` | Verbose output (show test names) |
| `-q` | Quiet output (dots only) |
| `--locals` | Show local variables in tracebacks |
| `--durations N` | Show N slowest tests |
| `-f` / `--failfast` | Stop on first failure |
| `-c` / `--catch` | Catch Ctrl-C and report results |
| `-b` / `--buffer` | Buffer stdout/stderr during tests |
| `-k PATTERN` | Run only tests matching pattern |
| `-s DIR` | Start directory for discovery (default: `.`) |
| `-p PATTERN` | File pattern for discovery (default: `test*.py`) |
| `-t DIR` | Top-level directory of project |

#### 4.8.4 Test Discovery

```bash
# Discover in specific directory with custom pattern
python -m unittest discover -s tests -p "*_test.py" -v
```

```text
test_login (tests.test_auth.TestAuth.test_login) ... ok
test_logout (tests.test_auth.TestAuth.test_logout) ... ok
test_register (tests.test_auth.TestAuth.test_register) ... ok
----------------------------------------------------------------------
Ran 3 tests in 0.012s

OK
```

#### 4.8.5 Show Slowest Tests

```bash
python -m unittest discover --durations 5
```

```text
...
5 slowest test durations
  0.234s test_large_dataset (test_perf.TestPerformance.test_large_dataset)
  0.156s test_network_call (test_api.TestAPI.test_network_call)
  ...
```

### 4.9 Doctest

Run doctests embedded in Python source files or text files:

```bash
python -m doctest mymodule.py -v
```

```text
Trying:
    add(1, 2)
Expecting:
    3
ok
...
1 items passed all tests:
   3 tests in mymodule
3 tests in 1 items.
3 passed and 0 failed.
Test passed.
```

| Flag | Purpose |
|------|---------|
| `-v` | Verbose output |
| `-o OPTION` / `--option OPTION` | Set doctest option (e.g., `ELLIPSIS`, `NORMALIZE_WHITESPACE`) |
| `-f` / `--fail-fast` | Stop on first failure |
| `file` | File(s) to test |

**Test a text file with embedded examples:**

```bash
python -m doctest README.txt
```

### 4.10 Code Compilation (compileall)

Pre-compile all `.py` files to `.pyc` bytecode:

```bash
python -m compileall .
```

```text
Compiling './app.py'...
Compiling './utils.py'...
Compiling './models.py'...
```

| Flag | Purpose |
|------|---------|
| `-l` | Do not recurse into subdirectories |
| `-r DEPTH` | Maximum recursion depth |
| `-f` | Force recompilation (even if `.pyc` is current) |
| `-q` | Quiet mode (`-qq` for completely silent) |
| `-b` | Write `.pyc` to source directory (legacy layout) |
| `-d DIR` | Directory to prepend to file paths in error messages |
| `-s STRIP` | Strip path prefix in `.pyc` files |
| `-p PREPEND` | Prepend path to `.pyc` files |
| `-x REGEX` | Exclude files matching regex |
| `-i FILE` | Read file list from FILE |
| `-j N` / `--workers N` | Parallel compilation with N workers |
| `--invalidation-mode MODE` | `timestamp`, `checked-hash`, or `unchecked-hash` |
| `-o LEVEL` | Optimization level (0, 1, or 2; can repeat) |
| `-e DIR` | Ignore symlinks pointing outside DIR |
| `--hardlink-dupes` | Hard-link duplicate `.pyc` files |

**Parallel compilation of a large project:**

```bash
python -m compileall -j 8 -q /opt/myapp
```

**Compile with multiple optimization levels:**

```bash
python -m compileall -o 0 -o 1 -o 2 mypackage/
```

This creates `.pyc` files for normal, `-O`, and `-OO` modes simultaneously.

> [!TIP]
> Use `--invalidation-mode checked-hash` for reproducible builds (CI/CD). Timestamp-based invalidation (the default) can cause stale bytecode if clocks differ between build and deploy hosts.

### 4.11 Compile Single Files (py_compile)

```bash
python -m py_compile script.py
python -m py_compile --quiet script1.py script2.py
```

| Flag | Purpose |
|------|---------|
| `-q` / `--quiet` | Suppress error output |
| `filenames` | One or more files to compile |

Returns exit code 0 on success, non-zero on syntax error. Useful in CI pipelines:

```bash
python -m py_compile $(find . -name '*.py') || echo "Syntax errors found"
```

---

## 5. Common Tasks

### 5.1 File Archive Operations

#### 5.1.1 ZIP Files (zipfile)

| Flag | Purpose |
|------|---------|
| `-l` / `--list` | List archive contents |
| `-e` / `--extract` | Extract archive |
| `-c` / `--create` | Create archive |
| `-t` / `--test` | Test archive integrity |
| `--metadata-encoding ENC` | Encoding for filenames in the archive |

**List contents:**

```bash
python -m zipfile --list archive.zip
```

```text
File Name                     Modified             Size
README.md                2026-01-15 10:30:00      1234
src/main.py              2026-01-15 10:30:00      5678
```

**Extract:**

```bash
python -m zipfile --extract archive.zip target_dir/
```

**Create:**

```bash
python -m zipfile --create new_archive.zip file1.py file2.py src/
```

**Test integrity:**

```bash
python -m zipfile --test archive.zip
```

#### 5.1.2 ZIP Applications (zipapp)

Create self-contained Python applications as ZIP files:

```bash
python -m zipapp myapp/ --output myapp.pyz --main "app:main" --python "/usr/bin/env python3"
```

| Flag | Purpose |
|------|---------|
| `source` | Source directory |
| `-o` / `--output` | Output filename |
| `-p` / `--python` | Python interpreter for shebang |
| `-m` / `--main` | Entry point (`module:function`) |
| `-c` / `--compress` | Compress archive contents |
| `--info` | Show info about an existing archive |

**Inspect an existing archive:**

```bash
python -m zipapp --info myapp.pyz
```

```text
Interpreter: /usr/bin/env python3
```

**Create a compressed, executable app:**

```bash
python -m zipapp myproject/ -o deploy.pyz -m "myproject.cli:main" -p "/usr/bin/env python3" --compress
```

Run it:

```bash
./deploy.pyz --help
```

#### 5.1.3 TAR Files (tarfile)

| Flag | Purpose |
|------|---------|
| `-l` / `--list` | List archive contents |
| `-e` / `--extract` | Extract archive |
| `-c` / `--create` | Create archive |
| `-t` / `--test` | Test archive |
| `-v` | Verbose output |
| `--filter FILTER` | Extraction filter for security |

**List:**

```bash
python -m tarfile --list backup.tar.gz
```

**Extract with filter:**

```bash
python -m tarfile --extract backup.tar.gz output_dir/ --filter=data
```

**Create:**

```bash
python -m tarfile --create backup.tar.gz src/ docs/ README.md
```

> [!IMPORTANT]
> Always use `--filter=data` when extracting untrusted tar archives. Without a filter, tar files can overwrite arbitrary files via path traversal (`../../etc/passwd`). Python 3.12+ emits a `DeprecationWarning` when no filter is specified, and a future version will default to `data`.

#### 5.1.4 Gzip (gzip)

```bash
python -m gzip file.txt          # Compress to file.txt.gz
python -m gzip -d file.txt.gz    # Decompress
```

| Flag | Purpose |
|------|---------|
| `--fast` | Fastest compression (level 1) |
| `--best` | Best compression (level 9) |
| `-d` / `--decompress` | Decompress instead of compress |
| `args` | Files to process |

### 5.2 UUID Generation (uuid)

```bash
python -m uuid
```

```text
4f3e2d1c-a0b9-8c7d-6e5f-4a3b2c1d0e9f
```

| Flag | Purpose |
|------|---------|
| `-u TYPE` / `--uuid TYPE` | UUID type: `uuid1`, `uuid3`, `uuid4` (default), `uuid5` |
| `-n NAMESPACE` / `--namespace NAMESPACE` | Namespace for uuid3/uuid5 (`@dns`, `@url`, `@oid`, `@x500`) |
| `-N NAME` / `--name NAME` | Name for uuid3/uuid5 |
| `-C COUNT` / `--count COUNT` | Number of UUIDs to generate |

**Generate 5 UUIDs:**

```bash
python -m uuid -C 5
```

```text
a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f
d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a
e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b
```

**Generate a DNS-namespaced UUID5:**

```bash
python -m uuid -u uuid5 -n @dns -N example.com
```

```text
cfbff0d1-9375-5685-968c-48ce8b15ae17
```

### 5.3 Random Number Generation (random)

```bash
python -m random -i 1 100
```

```text
42
```

| Flag | Purpose |
|------|---------|
| `-c` / `--choice` | Choose from provided items |
| `-i` / `--integer` | Random integer in range |
| `-f` / `--float` | Random float in range |
| `--test` | Run the module's test suite |
| `input` | Values to choose from (with `-c`) |

**Choose from a list:**

```bash
python -m random --choice Alice Bob Charlie Diana
```

```text
Charlie
```

**Random float between 0 and 1:**

```bash
python -m random -f 0 1
```

```text
0.7312849573
```

### 5.4 MIME Type Lookup (mimetypes)

```bash
python -m mimetypes photo.jpg
```

```text
type: image/jpeg encoding: None
```

| Flag | Purpose |
|------|---------|
| `-e` / `--extension` | Look up extension for a MIME type |
| `-l` / `--lenient` | Use lenient matching |
| `type` | Filename or MIME type to look up |

**Reverse lookup (MIME type to extension):**

```bash
python -m mimetypes -e application/pdf
```

```text
extension: .pdf
```

### 5.5 Calendar Display (calendar)

```bash
python -m calendar 2026
```

Displays the full year calendar in text format.

```bash
python -m calendar 2026 5
```

Displays May 2026.

| Flag | Purpose |
|------|---------|
| `-w N` | Column width (text mode) |
| `-l N` | Lines per week (text mode) |
| `-s N` | Spacing between months |
| `-m N` | Months per row |
| `-c CSS` / `--css CSS` | CSS file for HTML output |
| `-L LOCALE` / `--locale LOCALE` | Locale for month/day names |
| `-e ENCODING` / `--encoding ENCODING` | Output encoding |
| `-t TYPE` / `--type TYPE` | `text` or `html` |
| `-f DAY` / `--first-weekday DAY` | First day of the week (0=Mon, 6=Sun) |
| `year` | Year to display |
| `month` | Month to display (with year) |

**HTML calendar:**

```bash
python -m calendar --type html 2026 > calendar.html
```

**Start week on Sunday, US locale:**

```bash
python -m calendar -f 6 -L en_US.UTF-8 2026
```

### 5.6 Platform Information (platform)

```bash
python -m platform
```

```text
Linux-6.5.0-1-amd64-x86_64-with-glibc2.38
```

| Flag | Purpose |
|------|---------|
| `--terse` | Short platform string |
| `--nonaliased` | Do not use OS aliases |

```bash
python -m platform --terse
```

```text
Linux-6.5.0-1-amd64-x86_64-with-glibc2.38
```

### 5.7 Open URLs (webbrowser)

```bash
python -m webbrowser "https://docs.python.org"
python -m webbrowser -n "https://docs.python.org"   # New window
python -m webbrowser -t "https://docs.python.org"   # New tab
```

| Flag | Purpose |
|------|---------|
| `url` | URL to open |
| `-n` / `--new-window` | Open in new window |
| `-t` / `--new-tab` | Open in new tab |

### 5.8 Pickle Inspection (pickle / pickletools)

**Display pickle contents:**

```bash
python -m pickle data.pkl
```

**Disassemble a pickle file:**

```bash
python -m pickletools data.pkl
```

```text
    0: \x80 PROTO      5
    2: \x95 FRAME      18
   11: \x8c SHORT_BINUNICODE 'hello'
   18: \x94 MEMOIZE    (as 0)
   19: .    STOP
highest protocol among opcodes = 5
```

| Flag | Purpose |
|------|---------|
| `-o FILE` / `--output FILE` | Output file |
| `-m` / `--memo` | Show memo entries |
| `-l N` / `--indentlevel N` | Indentation level |
| `-a` / `--annotate` | Annotate with short descriptions |
| `-p` / `--preamble` | Show preamble |
| `pickle_file` | Pickle file to disassemble |

> [!CAUTION]
> Never unpickle data from untrusted sources. Pickle can execute arbitrary code during deserialization. Use `json`, `msgpack`, or other safe formats for data exchange.

### 5.9 Tokenizing Python Source (tokenize)

```bash
python -m tokenize script.py
```

```text
0,0-0,0:            ENCODING       'utf-8'
1,0-1,5:            NAME           'print'
1,5-1,6:            OP             '('
1,6-1,19:           STRING         "'Hello World'"
1,19-1,20:          OP             ')'
1,20-1,21:          NEWLINE        '\n'
2,0-2,0:            ENDMARKER      ''
```

| Flag | Purpose |
|------|---------|
| `-e` / `--exact` | Display exact token type names |
| `filename` | File to tokenize |

### 5.10 AST Inspection (ast)

Parse Python source and dump the Abstract Syntax Tree:

```bash
echo "x = 1 + 2" | python -m ast
```

```text
Module(
   body=[
      Assign(
         targets=[
            Name(id='x', ctx=Store())],
         value=BinOp(
            left=Constant(value=1),
            op=Add(),
            right=Constant(value=2)))],
   type_ignores=[])
```

| Flag | Purpose |
|------|---------|
| `infile` | Input file (default: stdin) |
| `-m MODE` / `--mode MODE` | Parse mode: `exec`, `eval`, `single`, `func_type` |
| `--no-type-comments` | Ignore type comments |
| `-a` / `--include-attributes` | Show line numbers and column offsets |
| `-i N` / `--indent N` | Indentation level |
| `--feature-version VER` | Target Python version for parsing |
| `-O N` / `--optimize N` | Optimization level (0, 1, 2) |
| `--show-empty` | Show empty lists/fields |

**Dump with attributes (line/col info):**

```bash
python -m ast -a script.py
```

### 5.11 Bytecode Disassembly (dis)

```bash
python -m dis script.py
```

```text
  1           RESUME                   0

  1           LOAD_NAME                0 (print)
              PUSH_NULL
              LOAD_CONST               0 ('Hello')
              CALL                     1
              POP_TOP
              RETURN_CONST             1 (None)
```

| Flag | Purpose |
|------|---------|
| `-C` / `--show-caches` | Show cache entries |
| `-O` / `--show-offsets` | Show byte offsets |
| `-P` / `--show-positions` | Show source positions |
| `-S` / `--specialized` | Show specialized opcodes |
| `infile` | File to disassemble |

**Full diagnostic disassembly:**

```bash
python -m dis -C -O -P -S script.py
```

### 5.12 Execution Tracing (trace)

Trace every line executed in a program:

```bash
python -m trace --trace script.py
```

```text
 --- modulename: script, funcname: <module>
script.py(1): x = 1
script.py(2): y = 2
script.py(3): print(x + y)
```

| Flag | Purpose |
|------|---------|
| `-c` / `--count` | Count line executions |
| `-t` / `--trace` | Print each line as executed |
| `-l` / `--listfuncs` | List functions called |
| `-T` / `--trackcalls` | Track caller/callee relationships |
| `-r` / `--report` | Generate report from count file |
| `-R` / `--no-report` | Do not generate report |
| `-f FILE` / `--file FILE` | Count data file |
| `-C DIR` / `--coverdir DIR` | Directory for coverage files |
| `-m` / `--missing` | Annotate missing (unexecuted) lines |
| `-s` / `--summary` | Print summary of coverage |
| `-g` / `--timing` | Print timing information |
| `--ignore-module MOD` | Ignore module in trace |
| `--ignore-dir DIR` | Ignore directory in trace |
| `--module` | Trace a module (like `-m`) |
| `progname` | Program to trace |

**Coverage analysis:**

```bash
python -m trace --count --coverdir coverage_out script.py
python -m trace --report --coverdir coverage_out --summary --missing
```

```text
lines   cov%   module   (path)
  100    87%   script   (script.py)
   50    92%   utils    (utils.py)
```

### 5.13 Profiling

#### 5.13.1 Sampling Profiler

The built-in sampling profiler collects stack samples at regular intervals with minimal overhead:

```bash
python -m profiling.sampling script.py
```

| Flag | Purpose |
|------|---------|
| `-r RATE` / `--sampling-rate RATE` | Samples per second |
| `-d SECS` / `--duration SECS` | Duration to profile |
| `-a` / `--all-threads` | Profile all threads |
| `--realtime-stats` | Show real-time statistics |
| `--native` | Include native (C) frames |
| `--no-gc` | Disable garbage collection during profiling |
| `--opcodes` | Profile at opcode granularity |
| `--async-aware` | Track async/await boundaries |
| `--subprocesses` | Follow child processes |
| `--blocking` | Block profiler thread until done |

**Mode selection:**

| Mode | Measures |
|------|----------|
| `wall` | Wall-clock time (default) |
| `cpu` | CPU time only |
| `gil` | GIL contention |
| `exception` | Exception frequency |

```bash
python -m profiling.sampling --mode cpu --native -r 1000 script.py
```

**Output formats:**

| Flag | Format |
|------|--------|
| `--pstats` | Python pstats format |
| `--collapsed` | Collapsed stacks (for FlameGraph) |
| `--flamegraph` | HTML flamegraph |
| `--gecko` | Gecko format (Firefox Profiler) |
| `--heatmap` | HTML heatmap |
| `--diff-flamegraph` | Differential flamegraph (compare two runs) |
| `--binary` | Binary format |
| `-o FILE` / `--output FILE` | Output file |
| `--browser` | Open output in browser automatically |
| `--compression` | Compress output |

**Generate a flamegraph:**

```bash
python -m profiling.sampling --flamegraph -o profile.html --browser script.py
```

**Live mode (top-like TUI):**

```bash
python -m profiling.sampling --live script.py
```

This displays a continuously updating view of the hottest functions, similar to `top` or `htop` for your Python code.

**Attach to a running process:**

```bash
python -m profiling.sampling --live 12345   # PID
```

**Sort and limit output:**

```bash
python -m profiling.sampling --sort tottime --limit 20 script.py
```

```bash
python -m profiling.sampling --no-summary -m mymodule
```

**Async-aware profiling:**

```bash
python -m profiling.sampling --async-aware --async-mode asyncio script.py
```

#### 5.13.2 Tracing Profiler

For deterministic (every-call) profiling with higher overhead:

```bash
python -m profiling.tracing script.py
```

#### 5.13.3 Built-in cProfile

The standard deterministic profiler:

```bash
python -m cProfile script.py
python -m cProfile -o output.prof script.py
python -m cProfile -s cumulative script.py
```

### 5.14 Interactive Interpreter (code)

Launch a clean interactive session:

```bash
python -m code
```

| Flag | Purpose |
|------|---------|
| `-q` | Quiet mode (no banner) |

```bash
python -m code -q
```

```text
>>>
```

### 5.15 IDLE IDE

Launch the built-in IDE:

```bash
python -m idlelib
# or
python -m idle
```

Requires `tkinter`. IDLE provides a multi-window text editor with syntax highlighting, autocompletion, debugger integration, and a shell window.

Set `IDLESTARTUP` for IDLE-specific startup code (separate from `PYTHONSTARTUP`):

```bash
export IDLESTARTUP=~/.idlerc/startup.py
```

### 5.16 Tkinter Demo

Verify your tkinter installation:

```bash
python -m tkinter
```

This opens a small demo window showing the Tcl/Tk version. If it fails, tkinter is not installed or Tcl/Tk is missing.

### 5.17 Turtle Graphics Demos

```bash
python -m turtledemo
```

Opens a gallery of turtle graphics examples. Great for learning or teaching.

---

## 5.18 Workflow Recipes

### Recipe 1: Create a Project from Scratch

```bash
mkdir myproject && cd myproject
python -m venv .venv
source .venv/bin/activate
pip install requests pytest
echo "import requests" > app.py
echo "def test_app(): assert True" > test_app.py
python -m unittest test_app -v
```

### Recipe 2: Validate All JSON Files in a Directory

```bash
for f in config/*.json; do
    python -m json.tool "$f" > /dev/null 2>&1 || echo "INVALID: $f"
done
```

### Recipe 3: Pre-Compile for Deployment

```bash
python -m compileall -j 8 --invalidation-mode checked-hash -o 0 -o 2 /opt/myapp
```

### Recipe 4: Quick File Server with Directory Listing

```bash
python -m http.server 9000 --directory /path/to/artifacts
```

### Recipe 5: Generate Multiple UUIDs for Config

```bash
python -m uuid -C 10 >> new_ids.txt
```

### Recipe 6: Profile and Visualize a Slow Script

```bash
python -m profiling.sampling --flamegraph -o perf.html --browser slow_script.py
```

### Recipe 7: Debug a Crashing Script

```bash
python -m pdb -c continue failing_script.py
# When it crashes, you land in the debugger at the exception
```

### Recipe 8: Find Untested Code

```bash
python -m trace --count --coverdir cov/ -m unittest discover
python -m trace --report --coverdir cov/ --summary --missing
```

### Recipe 9: Create a Self-Contained Tool

```bash
mkdir mytool
echo 'def main(): print("Hello from mytool!")' > mytool/app.py
echo '' > mytool/__init__.py
python -m zipapp mytool -m "app:main" -o mytool.pyz -p "/usr/bin/env python3"
chmod +x mytool.pyz
./mytool.pyz
```

```text
Hello from mytool!
```

### Recipe 10: Inspect What Python Sees in Your Code

```bash
python -m ast -a mymodule.py | head -50
python -m dis mymodule.py | head -50
python -m tokenize mymodule.py | head -20
```

### Recipe 11: Mass-Compile and Catch Syntax Errors

```bash
python -m py_compile $(find . -name '*.py' -not -path './.venv/*')
echo "Exit code: $?"
```

### Recipe 12: Test with Verbose Output and Duration Report

```bash
python -m unittest discover -v --durations 10
```

### Recipe 13: Extract a tar.gz Safely

```bash
python -m tarfile --extract archive.tar.gz output/ --filter=data
```

### Recipe 14: Compress a Log File

```bash
python -m gzip --best /var/log/app.log
```

### Recipe 15: Create a Deterministic Build

```bash
export SOURCE_DATE_EPOCH=$(date +%s)
python -m compileall --invalidation-mode checked-hash -q /opt/app
```

### Recipe 16: Interactive Async Experimentation

```bash
python -m asyncio
```

```python
>>> import aiohttp
>>> async with aiohttp.ClientSession() as s:
...     resp = await s.get('https://httpbin.org/get')
...     print(resp.status)
200
```

### Recipe 17: Benchmark GIL Contention (Free-Threaded Build)

```bash
PYTHON_GIL=0 python -m profiling.sampling --mode gil script.py
```

### Recipe 18: Generate a DNS-Based UUID for Idempotent Keys

```bash
python -m uuid -u uuid5 -n @dns -N "[email removed]"
```

### Recipe 19: MIME Type for CI Asset Upload

```bash
MIME=$(python -c "import mimetypes; print(mimetypes.guess_type('report.pdf')[0])")
echo "$MIME"
```

```text
application/pdf
```

### Recipe 20: Run Doctests Across Your Package

```bash
find mypackage -name '*.py' -exec python -m doctest {} -v \;
```

### Recipe 21: Profile Memory Allocations

```bash
python -X tracemalloc=10 script.py
```

In your code:

```python
import tracemalloc
tracemalloc.start(10)  # 10 frames deep
# ... run your code ...
snapshot = tracemalloc.take_snapshot()
for stat in snapshot.statistics('lineno')[:10]:
    print(stat)
```

### Recipe 22: Serve Local Docs Over HTTPS

```bash
# Generate self-signed cert (one-time)
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=localhost'
# Serve
python -m http.server 8443 --certfile cert.pem --keyfile key.pem --directory docs/
```

### Recipe 23: Debug with Automatic Breakpoint on Exception

```python
# In your code:
import sys

def excepthook(type, value, tb):
    import pdb, traceback
    traceback.print_exception(type, value, tb)
    pdb.post_mortem(tb)

sys.excepthook = excepthook
```

### Recipe 24: Calendar for Sprint Planning

```bash
python -m calendar --type html -f 0 2026 > sprint_calendar.html
```

### Recipe 25: Quick SQLite Analytics

```bash
python -m sqlite3 analytics.db "
CREATE TABLE IF NOT EXISTS events (ts TEXT, type TEXT, value REAL);
INSERT INTO events VALUES (datetime('now'), 'deploy', 1.0);
SELECT type, count(*), avg(value) FROM events GROUP BY type;
"
```

### Recipe 26: Attach Profiler to Running Process

```bash
# Get PID of your Python app
ps aux | grep python
# Attach sampling profiler
python -m profiling.sampling --live 54321
```

### Recipe 27: Parallel Test Discovery with Timing

```bash
python -m unittest discover -s tests -p "test_*.py" --durations 0 -v 2>&1 | tee test_results.txt
```

### Recipe 28: Convert Collapsed Stacks to Flamegraph

```bash
python -m profiling.sampling --collapsed -o stacks.txt script.py
# Then use any flamegraph tool with stacks.txt
```

---

## 6. Troubleshooting

### 6.1 Installation and Setup Errors

### Error: `command not found: python`

**Cause:** Python is not in your `PATH`, or it is installed as `python3`.

**Solution:**

```bash
# Try python3 instead
python3 --version

# On Windows, try the py launcher
py --version

# Check where Python is installed
which python3    # Linux/macOS
where python     # Windows
```

**Prevention:** Always check "Add to PATH" during installation. On Linux, some distros only ship `python3`.

---

### Error: `No module named pip`

**Cause:** pip was not installed with Python, or you are in a virtualenv that was created without pip.

**Solution:**

```bash
python -m ensurepip --upgrade
# Or download get-pip.py
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python get-pip.py
```

**Prevention:** Always install `python3-pip` alongside `python3` on Linux. Use `python -m venv` (which includes pip by default) rather than `virtualenv` without options.

---

### Error: `No module named '_ssl'`

**Cause:** Python was compiled from source without OpenSSL development headers.

**Solution:**

```bash
# Install OpenSSL dev headers
sudo apt install libssl-dev    # Debian/Ubuntu
sudo dnf install openssl-devel # Fedora

# Rebuild Python
./configure --enable-optimizations
make -j$(nproc)
make install
```

**Prevention:** Install all build dependencies before compiling. Check `python -c "import ssl"` immediately after building.

---

### Error: `No module named '_tkinter'`

**Cause:** Tk development libraries are missing.

**Solution:**

```bash
sudo apt install python3-tk tk-dev     # Debian/Ubuntu
sudo dnf install python3-tkinter tk-devel  # Fedora
brew install tcl-tk                     # macOS
```

**Prevention:** Install `tk-dev` before building from source. On macOS with Homebrew, you may need `--with-tcl-tk` or to set `CFLAGS`/`LDFLAGS` pointing to the Homebrew Tcl/Tk.

---

### Error: `externally-managed-environment`

**Cause:** PEP 668 — your system Python refuses global pip installs to avoid breaking the OS package manager.

**Solution:**

```bash
# Use a virtual environment (always preferred)
python -m venv .venv
source .venv/bin/activate
pip install package-name

# Or install to user site-packages
pip install --user package-name

# Or use pipx for CLI tools
pipx install black
```

**Prevention:** Always work in virtual environments. This error is a guardrail, not a bug.

---

### Error: `ModuleNotFoundError: No module named 'foo'`

**Cause:** The package is not installed in the current environment, or you are running the wrong Python interpreter.

**Solution:**

```bash
# Check which Python you're using
which python
python -c "import sys; print(sys.executable)"

# Check if the package is installed
pip list | grep foo

# Install it
pip install foo
```

**Prevention:** Activate your virtual environment before running scripts. Use `python -m pip install` instead of bare `pip` to ensure you target the right interpreter.

---

### Error: `SyntaxError: invalid syntax` (on valid Python 3 code)

**Cause:** You are accidentally running Python 2.

**Solution:**

```bash
python --version
# If it says Python 2.x, use python3 explicitly
python3 script.py
```

**Prevention:** Use `python3` explicitly, or create a virtual environment which always uses the Python it was created with.

---

### 6.2 Runtime Errors

### Error: `RecursionError: maximum recursion depth exceeded`

**Cause:** Infinite recursion, or a legitimate deep call stack.

**Solution:**

```python
import sys
sys.setrecursionlimit(10000)  # Increase from default 1000
```

For infinite recursion, use the debugger:

```bash
python -m pdb script.py
```

**Prevention:** Use iterative algorithms for deep structures. Consider `sys.setrecursionlimit()` only as a temporary measure.

---

### Error: `MemoryError`

**Cause:** The process exhausted available memory.

**Solution:**

```python
# Process data in chunks instead of loading all at once
with open('huge_file.csv') as f:
    for line in f:  # Lazy iteration
        process(line)
```

Profile memory:

```bash
python -X tracemalloc script.py
```

**Prevention:** Use generators, iterators, and streaming I/O for large datasets. Monitor with `tracemalloc`.

---

### Error: `UnicodeDecodeError: 'utf-8' codec can't decode byte`

**Cause:** Reading a file with the wrong encoding.

**Solution:**

```python
# Specify the correct encoding
with open('file.txt', encoding='latin-1') as f:
    data = f.read()

# Or detect encoding
import locale
print(locale.getpreferredencoding())
```

**Prevention:** Always specify `encoding=` when opening text files. Use `python -X utf8` to force UTF-8 mode globally.

---

### Error: `PermissionError: [Errno 13] Permission denied`

**Cause:** The file or directory is not writable by the current user.

**Solution:**

```bash
ls -la /path/to/file
chmod 644 /path/to/file    # If you own it
# Or install to user directory
pip install --user package
```

**Prevention:** Use virtual environments (which are in your home directory). Avoid `sudo pip install`.

---

### Error: `ConnectionRefusedError` (http.server)

**Cause:** The server is not running, the port is wrong, or another process holds the port.

**Solution:**

```bash
# Check what's on port 8000
lsof -i :8000       # Linux/macOS
netstat -ano | findstr :8000  # Windows

# Use a different port
python -m http.server 9000
```

**Prevention:** Check port availability before starting. Use `--bind 127.0.0.1` if you only need local access.

---

### Error: `json.decoder.JSONDecodeError` (json.tool)

**Cause:** The input is not valid JSON.

**Solution:**

```bash
# Check the exact error
python -m json.tool broken.json
```

```text
Expecting ',' delimiter: line 5 column 3 (char 67)
```

Common causes: trailing commas, single quotes, unquoted keys, comments.

**Prevention:** Use a JSON linter in your editor. Remember: JSON does not allow comments or trailing commas.

---

### Error: `OSError: [Errno 98] Address already in use`

**Cause:** Another process is already listening on the port.

**Solution:**

```bash
# Find and kill the process
lsof -i :8000
kill -9 <PID>
# Or use a different port
python -m http.server 8001
```

**Prevention:** Stop previous server instances before starting new ones.

---

### 6.3 Build and Compilation Errors

### Error: `Could not build wheels for ...`

**Cause:** Missing C compiler or development headers for a C extension.

**Solution:**

```bash
# Linux
sudo apt install build-essential python3-dev

# macOS
xcode-select --install

# Windows
# Install Visual Studio Build Tools
```

**Prevention:** Install build tools before attempting to install packages with C extensions.

---

### Error: `subprocess-exited-with-error` during pip install

**Cause:** The build backend (setuptools, meson, etc.) failed to compile the package.

**Solution:** Read the full error output. Common fixes:

```bash
# Update pip, setuptools, wheel
pip install --upgrade pip setuptools wheel

# Install system dependencies
sudo apt install libffi-dev libbz2-dev  # Example for cffi
```

**Prevention:** Check the package's installation docs for required system libraries.

---

### Error: `ImportError: libpython3.13.so.1.0: cannot open shared object file`

**Cause:** Python was built with `--enable-shared` but the library path is not configured.

**Solution:**

```bash
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
sudo ldconfig
```

**Prevention:** After building from source with shared libraries, run `ldconfig` and ensure `/etc/ld.so.conf.d/` includes the install prefix lib directory.

---

### 6.4 Virtual Environment Issues

### Error: `Error: Command '[...venv...]' returned non-zero exit status 1`

**Cause:** The `venv` module is not installed (common on Debian/Ubuntu where it is a separate package).

**Solution:**

```bash
sudo apt install python3-venv
# Then retry
python3 -m venv .venv
```

**Prevention:** Install `python3-venv` alongside `python3`.

---

### Error: `pip install` installs to system Python despite active venv

**Cause:** The virtualenv is not activated, or `pip` resolves to the system copy.

**Solution:**

```bash
# Verify activation
echo $VIRTUAL_ENV
which python
which pip

# Always use python -m pip
python -m pip install package-name
```

**Prevention:** Use `python -m pip` instead of bare `pip`. This ensures you use the interpreter-specific pip.

---

### Error: Virtual environment Python version mismatch

**Cause:** The Python binary the venv was created with was updated or removed.

**Solution:**

```bash
# Recreate the venv
rm -rf .venv
python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

**Prevention:** Pin the Python version in your project documentation. Use `pyenv` or similar tools to manage multiple versions.

---

### 6.5 Testing Errors

### Error: `unittest` finds no tests

**Cause:** Test files or methods do not match the expected naming pattern.

**Solution:**

```bash
# Default pattern is test*.py, method prefix is test_
python -m unittest discover -s tests -p "test_*.py" -v
```

Verify your test file and class structure:

```python
# tests/test_example.py
import unittest

class TestExample(unittest.TestCase):  # Must extend TestCase
    def test_something(self):          # Must start with test_
        self.assertEqual(1 + 1, 2)
```

**Prevention:** Follow the naming convention: files as `test_*.py`, classes as `Test*`, methods as `test_*`.

---

### Error: `ModuleNotFoundError` when running tests

**Cause:** The project root is not on `sys.path`.

**Solution:**

```bash
# Run from the project root
cd /path/to/project
python -m unittest discover

# Or set PYTHONPATH
PYTHONPATH=. python -m unittest discover -s tests
```

**Prevention:** Use `python -m unittest` (which adds `.` to `sys.path`) rather than running test files directly.

---

### Error: `ResourceWarning: unclosed file` during tests

**Cause:** Files opened without `with` blocks, or sockets not closed.

**Solution:**

```python
# Always use context managers
with open('file.txt') as f:
    data = f.read()
```

Run with warnings as errors to catch them all:

```bash
python -W error::ResourceWarning -m unittest discover
```

**Prevention:** Use `with` statements for all I/O resources. Run tests with `-W error::ResourceWarning` in CI.

---

### 6.6 Known CPython Issues

### Error: `I/O operation on closed file` with json.tool and JSON Lines

**Cause:** Known issue ([#132631](https://github.com/python/cpython/issues/132631)) where `--json-lines` can trigger a closed-file error on certain inputs.

**Solution:** Process JSON Lines in Python code as a workaround:

```python
import json, sys
for line in sys.stdin:
    line = line.strip()
    if line:
        print(json.dumps(json.loads(line), indent=2))
```

**Prevention:** Watch the issue for a fix in an upcoming patch release.

---

### Error: `dataclass(slots=True)` crashes with empty `__class__` cell

**Cause:** Known issue ([#148947](https://github.com/python/cpython/issues/148947)) where a dataclass method referencing `super()` or `__class__` with an empty cell triggers a crash when `slots=True`.

**Solution:** Avoid `slots=True` on dataclasses where methods use `super()` with complex inheritance, until the fix is released.

**Prevention:** Test dataclass definitions with `slots=True` explicitly in your test suite.

---

### Error: `dataclass` generates `__init__()` when class already defines one

**Cause:** Known issue ([#148941](https://github.com/python/cpython/issues/148941)). Use `@dataclass(init=False)` to prevent this.

**Solution:**

```python
from dataclasses import dataclass

@dataclass(init=False)
class Custom:
    x: int
    y: int

    def __init__(self, x: int, y: int = 0):
        self.x = x
        self.y = y
```

**Prevention:** Always specify `init=False` when providing a custom `__init__` on a dataclass.

---

### Error: `pkgutil.walk_packages(None)` raises `SkipTest` and stops iteration

**Cause:** Known issue ([#131684](https://github.com/python/cpython/issues/131684)). When `walk_packages` is called with `None` (all packages), importing test packages that raise `SkipTest` terminates the iterator.

**Solution:** Filter the package path to exclude test directories:

```python
import pkgutil, sys
for importer, modname, ispkg in pkgutil.walk_packages(
    path=[p for p in sys.path if 'test' not in p]
):
    print(modname)
```

**Prevention:** Always provide an explicit `path` argument to `walk_packages`.

---

### Error: `Exception ignored in: _removeHandlerRef` (logging)

**Cause:** Known issue ([#148910](https://github.com/python/cpython/issues/148910)). A race condition during interpreter shutdown when logging handlers are being garbage-collected.

**Solution:** This is cosmetic — it does not affect program correctness. To suppress:

```python
import logging
import atexit

def cleanup_logging():
    logging.shutdown()

atexit.register(cleanup_logging)
```

**Prevention:** Call `logging.shutdown()` explicitly before exit in long-running applications.

---

### Error: Endless polling / EOF on socket

**Cause:** Known issue ([#148950](https://github.com/python/cpython/issues/148950)) where certain socket configurations cause infinite polling on EOF.

**Solution:** Set socket timeouts explicitly:

```python
import socket
sock = socket.create_connection(('host', 80), timeout=30)
```

**Prevention:** Always configure socket timeouts. Never rely on default blocking behavior for production network code.

---

> [!WARNING]
> The issues listed above reference real CPython bug tracker entries. Check the linked issues for the latest status and available patches. Some may be fixed in newer patch releases.

---

## 7. FAQ

**Q: What is the difference between CPython and Python?**

A: CPython is the reference implementation of the Python language, written in C. When people say "Python" they almost always mean CPython. Other implementations exist (PyPy, Jython, IronPython, GraalPy), but CPython is the canonical one that defines the language behavior.

---

**Q: How do I check which Python version I'm running?**

A: Use any of these:

```bash
python --version
python -c "import sys; print(sys.version)"
python -c "import sys; print(sys.version_info)"
```

---

**Q: Can I have multiple Python versions installed at the same time?**

A: Yes. Use `pyenv` (Linux/macOS), the `py` launcher (Windows), or install different versions to different prefixes. Virtual environments isolate packages per-project.

---

**Q: What is a virtual environment and why should I use one?**

A: A virtual environment is an isolated Python installation with its own `site-packages`. It prevents dependency conflicts between projects and avoids polluting your system Python. Create one with `python -m venv .venv`.

---

**Q: How do I upgrade pip?**

A:

```bash
python -m pip install --upgrade pip
```

---

**Q: Why does `pip install` fail with `externally-managed-environment`?**

A: Your OS uses PEP 668 to protect its Python installation. Use a virtual environment (`python -m venv .venv`) or `pip install --user`. This is intentional and correct behavior.

---

**Q: How do I make a script executable on Linux/macOS?**

A: Add a shebang line and set the executable bit:

```python
#!/usr/bin/env python3
print("I'm executable!")
```

```bash
chmod +x script.py
./script.py
```

---

**Q: What does `python -m` do exactly?**

A: It searches `sys.path` for a module or package named by the argument and executes it as `__main__`. For packages, it runs `__main__.py` inside the package. It also adds the current directory to `sys.path`, which bare `python some/module.py` does not.

---

**Q: How do I see all installed packages?**

A:

```bash
pip list
pip list --outdated   # Show packages with newer versions available
pip freeze            # Output in requirements.txt format
```

---

**Q: How do I create a `requirements.txt`?**

A:

```bash
pip freeze > requirements.txt
pip install -r requirements.txt   # Reproduce the environment
```

---

**Q: How do I profile my Python code?**

A: For quick profiling:

```bash
python -m cProfile -s cumulative script.py
```

For production profiling with low overhead:

```bash
python -m profiling.sampling --flamegraph -o profile.html script.py
```

For memory profiling:

```bash
python -X tracemalloc=10 script.py
```

---

**Q: How do I debug a segmentation fault?**

A: Enable the fault handler:

```bash
python -X faulthandler script.py
```

Or in code:

```python
import faulthandler
faulthandler.enable()
```

This prints a Python traceback on SIGSEGV, SIGFPE, SIGABRT, SIGBUS, and SIGILL.

---

**Q: What is the GIL and how does free-threading work?**

A: The Global Interpreter Lock (GIL) prevents multiple threads from executing Python bytecode simultaneously. CPython 3.13+ offers an experimental free-threaded build (`python3.13t`) where the GIL can be disabled with `PYTHON_GIL=0`. This enables true parallel execution of Python threads but requires that all C extensions are thread-safe.

---

**Q: How do I check if my Python build is free-threaded?**

A:

```python
import sys
print(sys._is_gil_enabled())  # False = free-threaded, GIL disabled
```

Or check the build config:

```bash
python -c "import sysconfig; print(sysconfig.get_config_var('Py_GIL_DISABLED'))"
```

---

**Q: How do I serve files over HTTPS with the built-in server?**

A:

```bash
python -m http.server 8443 --certfile cert.pem --keyfile key.pem
```

Generate a self-signed certificate for testing:

```bash
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes
```

---

**Q: Can I use `await` in the regular REPL?**

A: No. Use the asyncio REPL:

```bash
python -m asyncio
>>> await asyncio.sleep(1)
```

The standard REPL does not support top-level `await`.

---

**Q: How do I compile Python from source with optimizations?**

A:

```bash
./configure --enable-optimizations --with-lto
make -j$(nproc)
```

`--enable-optimizations` runs PGO (Profile-Guided Optimization), which makes the resulting binary 10-20% faster but the build takes longer.

---

**Q: How do I set the Python hash seed for reproducible tests?**

A:

```bash
PYTHONHASHSEED=42 python -m unittest discover
```

Set to `0` to disable hash randomization entirely. This is useful for debugging test ordering issues but should not be used in production.

---

**Q: How do I suppress `.pyc` file creation?**

A:

```bash
export PYTHONDONTWRITEBYTECODE=1
# or
python -B script.py
```

---

**Q: How do I make Python print output immediately (no buffering)?**

A:

```bash
python -u script.py
# or
export PYTHONUNBUFFERED=1
```

This is essential for Docker containers and CI pipelines where you need to see output in real time.

---

**Q: How do I find where Python is looking for modules?**

A:

```python
import sys
for p in sys.path:
    print(p)
```

Or from the command line:

```bash
python -c "import sys; print('\n'.join(sys.path))"
```

---

**Q: How do I check what C extensions were built successfully?**

A: After building from source, the build output lists missing modules. You can also check:

```bash
python -m sysconfig
python -c "import _ssl; import _sqlite3; import _tkinter; print('All good')"
```

---

**Q: How do I use Python as a quick calculator?**

A:

```bash
python -c "print(2**256)"
python -c "from math import *; print(sqrt(2), pi, e)"
```

Or interactively:

```bash
python -q
>>> 365 * 24 * 60 * 60
31536000
```

---

**Q: What is `python -X dev` and when should I use it?**

A: Development mode enables additional runtime checks:
- Shows `DeprecationWarning` that is normally hidden
- Enables `faulthandler`
- Enables asyncio debug mode
- Shows `ResourceWarning` for unclosed files/sockets
- Enables debug hooks on memory allocators

Use it during development and in CI:

```bash
python -X dev script.py
```

---

**Q: How do I read Python documentation offline?**

A: Use `pydoc`:

```bash
python -m pydoc json
python -m pydoc json.dumps
python -m pydoc -b          # Start local doc server in browser
python -m pydoc -w json     # Write HTML file
```

---

**Q: How do I run a single test by name with unittest?**

A:

```bash
python -m unittest test_module.TestClass.test_method -v
# Or use -k for pattern matching
python -m unittest discover -k "test_login"
```

---

**Q: How do I install Python packages for just my user?**

A:

```bash
pip install --user package-name
```

Packages go to `~/.local/lib/pythonX.Y/site-packages/` (Linux) or `%APPDATA%\Python\` (Windows). Set `PYTHONUSERBASE` to change the location.

---

**Q: How do I list all built-in modules?**

A:

```python
import sys
print(sorted(sys.builtin_module_names))
```

For all available standard library modules:

```bash
python -c "import pkgutil; print([m.name for m in pkgutil.iter_modules()])" 2>/dev/null | tr ',' '\n'
```

---

**Q: How do I check timezone data availability?**

A: Python 3.9+ includes the `zoneinfo` module. Set `PYTHONTZPATH` to control where it looks for timezone data:

```python
from zoneinfo import ZoneInfo
from datetime import datetime
dt = datetime.now(ZoneInfo("America/New_York"))
print(dt)
```

If you get `ZoneInfoNotFoundError`, install the `tzdata` package:

```bash
pip install tzdata
```

---

**Q: How do I get TLS/SSL key logs for Wireshark debugging?**

A:

```bash
SSLKEYLOGFILE=/tmp/sslkeys.log python script.py
```

Then in Wireshark, set Preferences > Protocols > TLS > Pre-Master Secret log filename to `/tmp/sslkeys.log`.

---

**Q: How do I make `getopt` behave in strict POSIX mode?**

A: Set the environment variable:

```bash
POSIXLY_CORRECT=1 python script.py
```

This makes `getopt` stop processing options at the first non-option argument, which matches POSIX behavior.

---

_Generated May 2026 from python/cpython at 49918f5. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._