Python Fix, Crash & Optimization Guide

Python is a widely used general-purpose programming language favored for scripting, data work, web backends, and automation. This guide covers the install, dependency, and performance problems developers hit most often on Linux, macOS, and Windows.

Install / First Setup

• macOS (Homebrew): brew install python — this gives you python3 and pip3.
• Debian/Ubuntu: sudo apt update && sudo apt install python3 python3-venv python3-pip
• Windows: download the official installer from python.org, or run winget install Python.Python.3 and ensure "Add to PATH" is checked.
• Version manager (recommended): pyenv lets you install and switch between Python versions — pyenv install 3.12.0 && pyenv global 3.12.0.

Verify with python3 --version (or python --version on Windows).

Common Issues & Fixes

python: command not found (or python3: command not found)

Cause: The interpreter is not on your PATH, or only python3 exists on a system that aliases python to Python 2. Fix: Use python3 explicitly. On Windows, reinstall with "Add Python to PATH" enabled. On Unix you can add an alias: alias python=python3.

pip: command not found

Cause: pip was not installed, or it is namespaced as pip3. Fix: Run python3 -m pip --version. If missing on Debian/Ubuntu, sudo apt install python3-pip. Always prefer python3 -m pip ... so you target the correct interpreter.

venv fails: Error: [Errno 13] Permission denied or ensurepip is not available

Cause: The python3-venv package is missing (common on fresh Debian/Ubuntu). Fix: sudo apt install python3-venv, then python3 -m venv .venv and activate with source .venv/bin/activate (Windows: .venv\Scripts\activate).

SSL / TLS certificate error on pip install (behind a proxy)

Cause: Corporate proxy or firewall intercepts TLS, so pip cannot verify the PyPI certificate. Fix: Point pip at your mirror and trust it: python3 -m pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org -r requirements.txt. For repeated use, set it persistently with pip config set global.trusted-host "pypi.org files.pythonhosted.org". If a custom index is required, set PIP_INDEX_URL.

ModuleNotFoundError after a successful pip install

Cause: You installed the package into a different interpreter than the one running your script. Fix: Run python3 -m pip install <pkg> using the same python3 you use to run the code, and confirm with which python3. Inside a venv, activate it first.

Performance & Optimization

• Low-End (2–4 GB RAM): Use a virtualenv to avoid system conflicts, and rely on pip's local cache (pip cache) so repeats are offline. Avoid heavy in-process frameworks; prefer streaming over loading whole files.
• Mid (8–16 GB): Keep one venv per project, pin versions with pip freeze > requirements.txt, and use pip install --user only when you intentionally avoid venvs. For CPU-bound loops, call into native extensions (NumPy) rather than pure Python.
• Workstation (32 GB+): Run computation in PyPy for pure-Python hot loops, or use C extensions / multiprocessing. Increase pip parallelism is not a thing, but you can pre-build wheels and host a local index (e.g. pip install --index-url) for CI speed.

General: never install into the system Python; isolation via venv is the single biggest stability win.

Version & Compatibility Notes

• Python 2 reached end-of-life on 2020-01-01 and must not be used for new work.
• Actively used versions are Python 3.8 through 3.13; 3.9–3.12 are the most common in production.
• Some packages still require a minimum of 3.8 or 3.9 — check each project's requires-python.
• For exact, current version numbers and deprecation timelines, consult official release notes.

FAQ

Q: Should I use python or python3? A: On most Linux/macOS systems today python3 is the safe command because python may still resolve to Python 2 on older images. On Windows the installer typically provides python. Using python3 -m pip is the most portable habit.

Q: How do I completely isolate a project's dependencies? A: Create a virtual environment with python3 -m venv .venv, activate it, then pip install inside it. Everything stays in .venv and will not affect other projects.

Q: Why does pip install succeed but my import still fails? A: You likely installed into a different interpreter. Verify with which python3 and python3 -m pip show <pkg>; install through python3 -m pip install to guarantee the same target.

Q: How do I upgrade pip itself? A: python3 -m pip install --upgrade pip. Avoid system-package pip upgrades that can break OS tooling — prefer doing this inside a venv.

Q: Is sudo pip install ever okay? A: No. Installing into the system interpreter with sudo can break OS-managed packages. Use a venv, or --user install, instead.

Q: How do I run a specific older Python version? A: Install it with pyenv install 3.9.18 (or your version manager) and select it per project with pyenv local 3.9.18.

Related Guides

• Node.js Fix & Optimization Guide
• Rust Fix & Optimization Guide
• Go Fix & Optimization Guide
• Java Fix & Optimization Guide
• Dev RAM Calculator

Accuracy Note

Commands and paths reflect common, real-world setups as of 2026-08. Always verify against your installed version and OS. When in doubt, consult the official Python documentation.