pywho 0.3.3

pywho
One command to explain your Python environment, trace imports, and detect shadows.

Ever asked "Which Python am I running? Why did import X load that file? Do I have any files shadowing real modules?" — pywho answers all of it instantly.

📖 Read the full documentation

Quick Reference

Table of Contents

• Getting Started
• Why pywho?
• Usage
  • Environment Inspection
  • Import Tracing
  • Shadow Scanning
• Python API
• What It Detects
• Use Cases
• Platforms
• Development
• License

Getting Started

pip install pywho

Or with uv:

uv pip install pywho

Note: uvx pywho is not recommended — it runs inside uv's ephemeral sandbox, so the output reflects that temporary environment instead of your actual project. Always install pywho into the environment you want to inspect.

Why pywho?

• "Works on my machine" is the #1 debugging friction in Python. pywho kills it with one command.
• Paste the output into a GitHub issue, Slack message, or Stack Overflow question. Done.
• Zero dependencies. Pure stdlib. Works everywhere Python runs.
• Cross-platform. Linux, macOS, Windows. Python 3.9+.

Usage

Environment Inspection

pywho

  pywho - Python Environment Inspector
  ==============================================

  Interpreter
    Executable: /Users/dev/.venv/bin/python3
    Version:    3.12.3 (CPython)
    Compiler:   Clang 15.0.0 (clang-1500.3.9.4)
    Architecture: 64-bit

  Platform
    System:  Darwin 24.1.0
    Machine: arm64

  Virtual Environment
    Active: Yes
    Type:   uv
    Path:   /Users/dev/myproject/.venv
    Prompt: myproject

  Paths
    Prefix:        /Users/dev/myproject/.venv
    Base Prefix:   /opt/homebrew/Cellar/python@3.12/...
    Site-packages: /Users/dev/myproject/.venv/lib/python3.12/site-packages

  Package Manager
    Detected:    uv
    pip version: 24.0

  sys.path
    [0] (empty string = cwd)
    [1] /opt/homebrew/.../python312.zip
    [2] /opt/homebrew/.../python3.12
    ...

JSON output (for CI, scripts, sharing)

pywho --json

Include installed packages

pywho --packages

Skip pip version check (faster)

pywho --no-pip

Run as module

python -m pywho

Import Tracing

Trace exactly where an import resolves and why:

pywho trace requests

  Import Resolution: requests
  ========================================

  Resolved to: /Users/dev/.venv/lib/python3.12/site-packages/requests/__init__.py
  Module type: third-party (package)
  Cached:      No

  Search order:
    [0] /Users/dev/myproject        -> not found
    [1] /usr/lib/python3.12         -> not found
    [2] ~/.venv/lib/.../site-packages -> FOUND

Full search log

pywho trace json --verbose

JSON trace output

pywho trace requests --json

Shadow detection (single module)

$ pywho trace requests

  WARNING: './requests.py' shadows installed package 'requests'

Shadow Scanning

Scan an entire project for files that shadow stdlib or installed packages:

$ pywho scan .

  Found 2 shadow(s)
    2 HIGH (stdlib)

  [HIGH] math.py
         shadows stdlib module 'math'
  [HIGH] json.py
         shadows stdlib module 'json'

Scan with JSON output

pywho scan . --json

Scan stdlib only (skip installed packages)

pywho scan . --no-installed

Smart exclusions — these directories are automatically skipped: .venv, __pycache__, node_modules, dist, build, .git, and more.

Python API

Environment inspection

from pywho import inspect_environment

report = inspect_environment()

print(report.executable)        # /usr/bin/python3
print(report.venv.is_active)    # True
print(report.venv.type)         # "uv"
print(report.package_manager)   # "uv"

# Get JSON-serializable dict
data = report.to_dict()

Import tracing

from pywho import trace_import

trace = trace_import("requests")
print(trace.resolved_path)    # /path/to/requests/__init__.py
print(trace.module_type)      # ModuleType.THIRD_PARTY
print(trace.is_cached)        # True
print(trace.shadows)          # [] (empty = no shadows)

if trace.shadows:
    for s in trace.shadows:
        print(f"WARNING: {s.description}")

Shadow scanning

from pywho import scan_path
from pathlib import Path

results = scan_path(Path("."))
for r in results:
    print(f"[{r.severity.value.upper()}] {r.path} shadows {r.module_name}")

What It Detects

Interpreters

• CPython, PyPy, and other implementations
• Version, compiler, architecture (32/64-bit)
• Build date

Virtual environments

Package managers

Detects: pip, uv, conda, poetry, pipenv, pyenv

Paths

• sys.prefix, sys.base_prefix, sys.exec_prefix
• All site-packages directories
• Full sys.path with index numbers

Packages

With --packages: lists all installed packages with versions and locations.

Import shadows

• Single-module detection via pywho trace
• Project-wide scanning via pywho scan
• Severity levels: HIGH (stdlib) and MEDIUM (installed)

Use Cases

Platforms

Development

git clone https://github.com/AhsanSheraz/pywho.git
cd pywho
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest -v
mypy src/pywho

License

MIT