Python’s sitecustomize.py & usercustomize.py — The Hidden Startup Files You Didn’t Know About

You open a Python REPL, and before you type a thing, your company’s logging setup is already loaded, your custom tools are available, and even your favorite pretty-printer is active.

You didn’t run any imports. You didn’t change PYTHONPATH. It just… happened.

The secret? sitecustomize.py and usercustomize.py — two special Python files that run automatically every time the interpreter starts.

What Are They?

• sitecustomize.py → For team-wide or environment-wide settings. Lives in site-packages or any site directory.
• usercustomize.py → For your personal developer preferences. Lives in your user site directory (site.getusersitepackages()).

Both are optional. If Python finds them, it runs them before any other code.

Where Python Looks for Them

You can find their search paths with:

import site
print(site.getsitepackages())      # System/venv paths
print(site.getusersitepackages())  # User path

If a sitecustomize.py or usercustomize.py exists there, Python will execute it.

Real-Life Example: Company-Wide Logging Setup

At one of my past workplaces, we had dozens of microservices, each with its own logging setup.
Developers kept forgetting to configure logs consistently—leading to messy output in staging and production.

Solution:
We added a sitecustomize.py in our shared virtual environment’s site-packages folder:

# sitecustomize.py
import logging
logging.basicConfig(
    level=logging.INFO,
    format="%(levelname)s %(asctime)s [%(name)s]: %(message)s"
)

Result:

• Every developer and service using that venv got uniform logging format automatically.
• No need to duplicate logging setup in every project.

How to Create Them

User Level:

python -c "import site; print(site.getusersitepackages())"

Go to that folder and create:

# usercustomize.py
print("[usercustomize] Python just started!")

Run python again — you’ll see your message before the prompt.

Common Use Cases

✅ Set global logging formats
✅ Configure warnings (e.g., show all by default)
✅ Add developer helpers in REPL (pretty printers, rich tracebacks)
✅ Quick environment tweaks for experiments

Risks & Gotchas

⚠ Hidden Side Effects — Code runs even when you don’t expect it.
⚠ Security Risks — A malicious file in these paths will run automatically.
⚠ Debugging Pain — If behavior changes mysteriously, check for these files.

Best Practices

• Keep them minimal — avoid heavy imports or long-running code
• Use environment variables to toggle behavior
• For adding paths, prefer .pth files instead of code
• Document them in your project setup guide

Disabling or Debugging

If something weird is happening and you suspect sitecustomize.py or usercustomize.py:

python -S  # Skip the 'site' module entirely

Recap

• sitecustomize.py and usercustomize.py are Python’s hidden startup hooks
• Great for consistent, global settings across all scripts
• Use them for helpful defaults, not heavy logic
• Always document and audit them for security