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):

brew install python@3.13
python3 --version

Python 3.13.x

On Ubuntu / Debian:

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

Python 3.13.x

On Windows (installer):

Download from python.org/downloads. Check "Add python.exe to PATH" during installation. Then open a terminal:

python --version

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:

print("Hello from CPython!")

Run it:

python hello.py

Hello from CPython!

1.3 The Interactive REPL

Launch the REPL for quick experiments:

python

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

Type expressions directly:

>>> 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:

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

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:

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

2.2 Windows Installation

2.2.1 Official Installer

1. Download from 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:

python --version
pip --version

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

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:

py -3.13 --version
py -3.12 --version
py --list

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)

brew install python@3.13

Homebrew links python3 and pip3 automatically. Verify:

python3 --version
which python3

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

2.3.2 Official Installer

Download the .pkg from 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:

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

Fedora:

sudo dnf install python3 python3-pip python3-devel

Arch Linux:

sudo pacman -S python python-pip

2.4.2 deadsnakes PPA (Ubuntu — Multiple Versions)

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)

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

Python 3.13.x

2.5 Building from Source

For contributors or when you need a custom build:

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

Linux / macOS:

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

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

Build dependencies (Debian/Ubuntu):

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):

PCbuild\build.bat -p x64

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

2.6 Verifying Your Installation

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

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

Check that key modules are available:

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

OpenSSL 3.0.x ...
3.45.x
8.6

2.7 Bootstrap pip with ensurepip

If pip is missing from your installation:

python -m ensurepip --upgrade

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

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.

3. Configuration

3.1 Environment Variables

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

3.2 REPL Configuration

3.3 Startup File

Create ~/.pythonrc to customize every interactive session:

# ~/.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:

export PYTHONSTARTUP=~/.pythonrc

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

3.4 Warning Filters

Control which warnings appear at runtime:

# 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:

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

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

3.5 Free-Threading (GIL Control)

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

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

3.7 The sysconfig Module

View every build-time configuration variable:

python -m sysconfig

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

python script.py
python script.py arg1 arg2

Arguments are available via sys.argv:

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

4.1.2 Execute a String

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

4.1.3 Execute a Module

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:

python myproject/
python myapp.zip

4.1.5 Read from stdin

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

4.2 Interpreter Flags

Useful -X Options

4.3 The asyncio REPL

The asyncio REPL lets you await coroutines directly without boilerplate:

python -m asyncio

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

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

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

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

4.4.2 Set Breakpoints in Code

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

4.4.3 Essential pdb Commands

4.4.4 Post-Mortem Debugging

python -m pdb -c continue script.py

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

Or from code:

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:

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

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

Flag Reference

Examples

Validate a JSON file:

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

If invalid, you get a clear error:

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

Sort keys and compact output:

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

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

Process JSON Lines (JSONL):

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

Each line is parsed and pretty-printed independently.

Reformat with tabs:

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

Pipe from curl:

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:

python -m sqlite3 mydb.sqlite3

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>

Execute SQL directly:

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

Create a database and table:

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;"

(1, 'Widget', 100)

4.7 HTTP Server (http.server)

Serve files from any directory:

python -m http.server 8080

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:

python -m http.server 8080 --bind 127.0.0.1

Serve a specific directory:

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

HTTPS Server (with TLS):

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

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

python -m unittest discover

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

OK

4.8.2 Run Specific Tests

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

4.8.3 Flag Reference

4.8.4 Test Discovery

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

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

python -m unittest discover --durations 5

...
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:

python -m doctest mymodule.py -v

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.

Test a text file with embedded examples:

python -m doctest README.txt

4.10 Code Compilation (compileall)

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

python -m compileall .

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

Parallel compilation of a large project:

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

Compile with multiple optimization levels:

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)

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

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

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)

List contents:

python -m zipfile --list archive.zip

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

Extract:

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

Create:

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

Test integrity:

python -m zipfile --test archive.zip

5.1.2 ZIP Applications (zipapp)

Create self-contained Python applications as ZIP files:

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

Inspect an existing archive:

python -m zipapp --info myapp.pyz

Interpreter: /usr/bin/env python3

Create a compressed, executable app:

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

Run it:

./deploy.pyz --help

5.1.3 TAR Files (tarfile)

List:

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

Extract with filter:

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

Create:

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)

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

5.2 UUID Generation (uuid)

python -m uuid

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

Generate 5 UUIDs:

python -m uuid -C 5

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:

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

cfbff0d1-9375-5685-968c-48ce8b15ae17

5.3 Random Number Generation (random)

python -m random -i 1 100

42

Choose from a list:

python -m random --choice Alice Bob Charlie Diana

Charlie

Random float between 0 and 1:

python -m random -f 0 1

0.7312849573

5.4 MIME Type Lookup (mimetypes)

python -m mimetypes photo.jpg

type: image/jpeg encoding: None

Reverse lookup (MIME type to extension):

python -m mimetypes -e application/pdf

extension: .pdf

5.5 Calendar Display (calendar)

python -m calendar 2026

Displays the full year calendar in text format.

python -m calendar 2026 5

Displays May 2026.

HTML calendar:

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

Start week on Sunday, US locale:

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

5.6 Platform Information (platform)

python -m platform

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

python -m platform --terse

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

5.7 Open URLs (webbrowser)

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

5.8 Pickle Inspection (pickle / pickletools)

Display pickle contents:

python -m pickle data.pkl

Disassemble a pickle file:

python -m pickletools data.pkl

    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

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)

python -m tokenize script.py

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      ''

5.10 AST Inspection (ast)

Parse Python source and dump the Abstract Syntax Tree:

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

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

Dump with attributes (line/col info):

python -m ast -a script.py

5.11 Bytecode Disassembly (dis)

python -m dis script.py

  1           RESUME                   0

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

Full diagnostic disassembly:

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

5.12 Execution Tracing (trace)

Trace every line executed in a program:

python -m trace --trace script.py

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

Coverage analysis:

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

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:

python -m profiling.sampling script.py

Mode selection:

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

Output formats:

Generate a flamegraph:

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

Live mode (top-like TUI):

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:

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

Sort and limit output:

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

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

Async-aware profiling:

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

5.13.2 Tracing Profiler

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

python -m profiling.tracing script.py

5.13.3 Built-in cProfile

The standard deterministic profiler:

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:

python -m code

python -m code -q

>>>

5.15 IDLE IDE

Launch the built-in IDE:

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):

export IDLESTARTUP=~/.idlerc/startup.py

5.16 Tkinter Demo

Verify your tkinter installation:

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

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

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

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

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

Recipe 4: Quick File Server with Directory Listing

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

Recipe 5: Generate Multiple UUIDs for Config

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

Recipe 6: Profile and Visualize a Slow Script

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

Recipe 7: Debug a Crashing Script

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

Recipe 8: Find Untested Code

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

Recipe 9: Create a Self-Contained Tool

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

Hello from mytool!

Recipe 10: Inspect What Python Sees in Your Code

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

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

Recipe 12: Test with Verbose Output and Duration Report

python -m unittest discover -v --durations 10

Recipe 13: Extract a tar.gz Safely

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

Recipe 14: Compress a Log File

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

Recipe 15: Create a Deterministic Build

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

Recipe 16: Interactive Async Experimentation

python -m asyncio

>>> 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)

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

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

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

Recipe 19: MIME Type for CI Asset Upload

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

application/pdf

Recipe 20: Run Doctests Across Your Package

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

Recipe 21: Profile Memory Allocations

python -X tracemalloc=10 script.py

In your code:

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

# 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

# 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

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

Recipe 25: Quick SQLite Analytics

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

# 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

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

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:

# 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:

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:

# 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:

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:

# 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:

# 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:

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:

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

For infinite recursion, use the debugger:

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:

# 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:

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:

# 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:

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:

# 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:

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

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:

# 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:

# 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:

# 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:

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:

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:

# 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:

# 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:

# 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:

# 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:

# 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:

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

Run with warnings as errors to catch them all:

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) where --json-lines can trigger a closed-file error on certain inputs.

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

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) 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). Use @dataclass(init=False) to prevent this.

Solution:

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). 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:

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). 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:

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) where certain socket configurations cause infinite polling on EOF.

Solution: Set socket timeouts explicitly:

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:

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:

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:

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

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:

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:

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

Q: How do I profile my Python code?

A: For quick profiling:

python -m cProfile -s cumulative script.py

For production profiling with low overhead:

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

For memory profiling:

python -X tracemalloc=10 script.py

Q: How do I debug a segmentation fault?

A: Enable the fault handler:

python -X faulthandler script.py

Or in code:

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:

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

Or check the build config:

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:

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

Generate a self-signed certificate for testing:

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:

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:

./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:

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:

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

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

A:

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:

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

Or from the command line:

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:

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:

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

Or interactively:

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:

python -X dev script.py

Q: How do I read Python documentation offline?

A: Use pydoc:

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:

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:

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:

import sys
print(sorted(sys.builtin_module_names))

For all available standard library modules:

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:

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:

pip install tzdata

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

A:

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:

POSIXLY_CORRECT=1 python script.py

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