Skip to main content

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

CI PyPI version Python versions License Downloads Coverage Documentation


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

Command Description
pywho Show a full report of your Python environment
pywho --json Output environment report as JSON
pywho --packages Include all installed packages in the report
pywho --no-pip Skip pip version detection (faster)
pywho trace <module> Trace where an import resolves and show search order
pywho trace <module> --verbose Trace with full sys.path search log
pywho trace <module> --json Trace output as JSON
pywho scan . Scan project for files that shadow stdlib/installed packages
pywho scan . --no-installed Scan against stdlib only (skip installed packages)
pywho scan . --json Scan output as JSON
python -m pywho Run as a Python module

Table of Contents

Getting Started

pip install pywho

Or with uv:

uv add --dev pywho

For one-off usage without changing project dependencies:

uv run --with pywho 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. Use uv add --dev pywho for regular project use, or uv run --with pywho pywho for one-off checks.

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.10+.

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

Type Detection method
venv sys.prefix != sys.base_prefix
virtualenv orig-prefix.txt in lib directory
uv uv = in pyvenv.cfg
conda CONDA_DEFAULT_ENV env var
poetry POETRY_ACTIVE env var
pipenv PIPENV_ACTIVE env var

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

Scenario Command
Debug "works on my machine" pywho --json → paste into issue
Verify onboarding setup pywho
CI environment snapshots pywho --json --packages > env.json
Find why an import is wrong pywho trace <module>
Audit project for shadows pywho scan .
Ask users for their env "Please run pywho"

Platforms

Platform Status
Linux ✅ Supported
macOS ✅ Supported
Windows ✅ Supported
Python Status
3.10+ ✅ Supported
3.10 – 3.15 ✅ Tested in CI

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

Metadata

Release files for pywho 0.3.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pywho 0.3.4
File Size Uploaded Provenance Actions
pywho-0.3.4.tar.gz 19.3 kB With provenance Details for pywho-0.3.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pywho 0.3.4
File Interpreter ABI Platform Actions
pywho-0.3.4-py3-none-any.whl Python 3 none any Details for pywho-0.3.4-py3-none-any.whl

Total release size: 39.9 kB

Release files / pywho-0.3.4.tar.gz

Download URL pywho-0.3.4.tar.gz
Size 19.3 kB
Tags Source
SHA-256 checksum
How to use checksums
0ba8342853f8bee650927268f18232321d37e1855a2f1db7e17aed47a9928f63
BLAKE2b-256 checksum
How to use checksums
c7d5d2c47d6c7e2a944be360383cf229011839e7ea9bc30b1c59708ab4ebaa90
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

Release files / pywho-0.3.4-py3-none-any.whl

Download URL pywho-0.3.4-py3-none-any.whl
Size 20.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4b736980c3f4bf8143ee087166046a1f161c8a27c75998b259b8b418746d065c
BLAKE2b-256 checksum
How to use checksums
a129f0941f448db785951fdc8f9fa2a021c9f48a25696ccdcb2dd9d2e66d01e5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

Security for pywho 0.3.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pywho-0.3.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page