Python site Customization — Core Concepts

Understand how Python's site module configures sys.path, loads startup scripts, and manages site-packages — the hidden foundation of every Python installation.

Why site customization matters

The site module runs automatically during Python startup (unless you use the -S flag). It configures the environment that makes pip-installed packages importable, enables virtual environments, and provides hooks for system-wide customization. Understanding it explains why packages install where they do and how to influence Python’s startup behavior.

What site does at startup

The site module performs these steps in order:

1. Adds site-packages directories to sys.path

It computes the site-packages directory for your Python installation and appends it to sys.path. The exact location depends on your OS:

Linux: /usr/lib/python3.x/site-packages or /usr/local/lib/python3.x/dist-packages
macOS: /Library/Frameworks/Python.framework/.../site-packages
Windows: C:\Python3x\Lib\site-packages

For virtual environments, it uses the venv’s site-packages directory instead.

2. Processes .pth files

Any .pth file in site-packages is read. Each line that contains a directory path is added to sys.path. Lines starting with import are executed as Python statements. This is how tools like setuptools and coverage hook into the startup process.

Example .pth file:

# easy-install.pth
/home/user/dev/my-project/src
import coverage; coverage.process_startup()

3. Runs sitecustomize.py

If a file named sitecustomize.py exists anywhere on sys.path, it is imported automatically. System administrators use this for global configuration:

# /usr/lib/python3.x/sitecustomize.py
import sys
sys.setdefaultencoding = None  # Not available normally, but example
import locale
locale.setlocale(locale.LC_ALL, '')

4. Runs usercustomize.py

If the ENABLE_USER_SITE flag is active (default when not in a virtual environment), Python also imports usercustomize.py from the user-specific site directory. This lets individual users set personal preferences without modifying the system installation.

5. Adds interactive helpers

In interactive mode, site adds quit(), exit(), copyright, credits, and license to the built-in namespace.

The user site-packages directory

Each user has a personal site-packages directory (used by pip install --user):

import site
print(site.getusersitepackages())
# Linux: ~/.local/lib/python3.x/site-packages
# macOS: ~/Library/Python/3.x/lib/python/site-packages
# Windows: %APPDATA%\Python\Python3x\site-packages

This directory is added to sys.path unless:

You are in a virtual environment (VIRTUAL_ENV is set)
You use the -s flag
PYTHONNOUSERSITE is set

Virtual environments and site

When you activate a virtual environment, the site module detects the pyvenv.cfg file in the Python executable’s directory. This file tells site to:

Use the venv’s site-packages instead of the system one
Optionally include or exclude the system site-packages (based on include-system-site-packages = true/false in pyvenv.cfg)
Disable user site-packages

This is why pip install inside a venv puts packages in the venv directory, not the system directory.

Inspecting site configuration

Run python -m site to see everything the site module configured:

sys.path = [
    '/home/user/project',
    '/usr/lib/python3.11',
    '/usr/lib/python3.11/lib-dynload',
    '/home/user/.local/lib/python3.11/site-packages',
    '/usr/lib/python3.11/site-packages',
]
USER_BASE: '/home/user/.local'
USER_SITE: '/home/user/.local/lib/python3.11/site-packages'
ENABLE_USER_SITE: True

Common misconception

Many people think sitecustomize.py needs to be in a specific location. It can actually be anywhere on sys.path — the first one found is imported. This means putting a sitecustomize.py in your project directory could accidentally affect all Python programs run from that directory.

Disabling site with -S

Running python -S skips the entire site module. This means:

No site-packages on sys.path
No .pth file processing
No sitecustomize.py or usercustomize.py
No quit(), exit() helpers

This is useful for debugging path issues or when you need the fastest possible startup.

The one thing to remember: The site module is Python’s invisible bootstrapper — it wires up site-packages, processes .pth files, and runs startup scripts, making it the reason pip install packages are importable and virtual environments work correctly.

pythonconfigurationstartup