bash
which pythonNotes
A quick first check after activating a venv.
Python venv Troubleshooting Cheat Sheet
Diagnose activation problems, broken pip, wrong interpreter selection, PATH confusion, and environment drift in Python virtual environments.
Export
Copy the compact sheet, download it, or print it.
Download
`D` dense toggle · `C` copy all
Wrong interpreter or pip
Find out why the shell is resolving the wrong Python or pip.
bash
which pipNotes
Useful when `pip` appears to install into the wrong location.
bash
command -v pythonNotes
Another common way to inspect command resolution in POSIX shells.
Print sys.executable
Verify the exact interpreter the shell is using.
bashANYsys.executablepythoninspect
bash
python -c "import sys; print(sys.executable)"Notes
This is often more trustworthy than assumptions based on PATH alone.
Use python -m pip for installs
Avoid ambiguity by tying pip to the active interpreter.
bashANYpython-m-pipbest-practicepip
bash
python -m pip install -r requirements.txtNotes
This is a best practice when multiple Python installations are present.
Activation issues
Handle shell and Windows policy issues.
bash
source .venv/bin/activateNotes
The most common activation command on POSIX systems.
bash
source .venv/bin/activate.fishNotes
Use the shell-specific script when you are not using bash/zsh.
powershell
.venv\Scripts\Activate.ps1Notes
Standard PowerShell activation command for a venv.
Allow local PowerShell scripts
Fix execution policy for venv activation scripts.
powershellWINDOWSexecution-policypowershellwindows
powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSignedNotes
A common resolution when PowerShell blocks `Activate.ps1`.
bash
rehashNotes
Useful when a shell keeps remembering an old command location after activation.
Repair pip and packaging state
Recover from missing pip or broken packaging tools.
bash
python -m ensurepip --default-pipNotes
Use this when pip is missing after environment creation or corruption.
Upgrade bundled pip
Reinstall or upgrade pip from the standard library bundle.
bashANYensurepipupgraderepair
bash
python -m ensurepip --upgradeNotes
Useful after partial uninstall or a broken pip state.
bash
python -m pip install --upgrade --force-reinstall pip setuptools wheelNotes
A common recovery step when package operations start behaving strangely.
Purge cache during package troubleshooting
Clear cached artifacts before retrying installs.
bashANYcachepurgepip
bash
python -m pip cache purgeNotes
Useful when stale caches appear to contribute to install failures.
Full environment reset
Delete and recreate when the environment is no longer trustworthy.
bash
rm -rf .venv && python -m venv .venv && source .venv/bin/activate && python -m pip install -U pip setuptools wheel && python -m pip install -r requirements.txtNotes
Often the fastest and cleanest fix when a venv becomes inconsistent.
Delete and recreate on PowerShell
Rebuild from scratch on Windows.
powershellWINDOWSresetrecreatewindows
powershell
Remove-Item -Recurse -Force .venv; py -m venv .venv; .venv\Scripts\Activate.ps1; python -m pip install -U pip setuptools wheel; python -m pip install -r requirements.txtNotes
PowerShell equivalent of a full environment rebuild.
Confirm imports after rebuild
Smoke-test a rebuilt environment quickly.
bashANYsmoke-testimportsrebuild
bash
python -c "import pkgutil; print('requests' in [m.name for m in pkgutil.iter_modules()])"Notes
A quick example of checking whether an expected package is visible after reinstall.
More in Python venv
Python venv Project Setup Cheat Sheet
Project-level setup patterns for Python virtual environments, pyproject.toml, editable installs, dev tools, and team onboarding.
Python venv + pip Cheat Sheet
Package installation, requirements, editable installs, wheel workflows, and dependency troubleshooting inside Python virtual environments.
Python venv Cheat Sheet
Comprehensive Python venv reference covering creation, activation, pip usage, requirements, inspection, and recovery workflows.