Every Python developer hits the same set of environment problems in their first year: which virtual env tool to pick, why pip install succeeded but the import fails, what the "externally-managed-environment" error means, how to run two Python versions side by side, why the Windows python command opens Microsoft Store. This pillar page is a curated reference for the 10 problems that come up most on r/learnpython and Stack Overflow, grouped into five sub-clusters: Installation, Virtual Environments, Package Management, Project Structure, and Distribution. Each entry is a full explainer with code, diagrams, and decision rules. This pillar page sits inside our broader learn Python complete guide.
Key Takeaways
Five sub-clusters cover every environment problem: installation, virtual envs, package management, project structure, and distribution.
The 2026 default toolchain is uv. One Rust binary replaces pip, venv, virtualenv, pyenv, pip-tools, and most of Poetry and pipx.
The conda family still wins for native scientific stacks. uv handles pure Python; conda/mamba/pixi handle CUDA, GDAL, R interop.
Reach for a venv before reaching for PYTHONPATH or --break-system-packages. Most environment errors are project-scoping problems with simpler fixes than they look.
This pillar page is reference, not tutorial. Each entry is a decision rule plus the explainer; jump in where your problem is.
The whole environment story in one bento-grid map. Five sub-clusters, ten explainers, one set of decision rules.
How to Use This Reference
Three ways readers usually approach this pillar page:
You have a specific problem. Jump straight to the sub-cluster that matches it (import failing? → Virtual environments. Windows install? → Installation). Each explainer is self-contained and you don't need to read the others first.
You're setting up a new project. Read the venv decision guide first, then the imports guide if your project is more than one file. The other entries become relevant when the corresponding error shows up; you'll find them via the cross-links.
You're learning Python tooling end-to-end. Read in order: venv guide, then ModuleNotFoundError, then PEP 668, then conda vs pip vs uv. By the end you'll have the mental model that the other six explainers build on, and you won't need to memorize each tool's CLI individually.
The 2026 short answer for new projects: install uv, use a venv (or let uv manage one for you), pin Python versions with .python-version, and reach for conda only when native scientific deps demand it. Everything below is the layer underneath that summary. If you don't already have uv installed, that's a one-line bootstrap that's worth doing before you read further.
Installation
How Python and pip get onto your machine, and what's changed in 2026.
"externally-managed-environment" Pip Error: What PEP 668 Changed
The pip error introduced in 2023 when Debian, Ubuntu, Fedora, Arch, and Homebrew started shipping the EXTERNALLY-MANAGED marker file. What PEP 668 actually does, why it's a good change, five fix paths (venv, uv, pipx, system package manager, --break-system-packages) with a decision rule for each, and the per-distro file content. Read the full explainer →
Install Python and pip on Windows in 2026: Five Paths, py Launcher, Store Stub Trap
The Windows install story changed when Python 3.14 shipped the new Python Install Manager (pymanager) and the traditional MSI installer was marked deprecated. Five paths compared (pymanager, python.org MSI, Microsoft Store, Scoop, uv), the Store Stub trap that opens Microsoft Store when you type python, and the py launcher patterns every Windows Python user should know. Read the full explainer →
Multiple Python Versions on One Machine: pyenv, uv, py Launcher, asdf, mise
The classic problem of running 3.10 for a legacy project and 3.13 for a new one. Six version managers compared side-by-side (uv, pyenv, py launcher, asdf, mise, conda), how shims actually intercept the python command, per-project pinning with .python-version, the macOS Homebrew trap, and how to clean up old Pythons safely. Read the full explainer →
Virtual Environments
The isolation layer between your projects, your system Python, and the chaos of competing dependency versions.
venv vs virtualenv vs Pipenv vs Poetry vs pipx vs uv: The 2026 Decision Guide
Six environment tools compared with a decision flowchart, the PEP 405 internals every Python dev should understand once, speed benchmarks, and step-by-step migration paths between every common pair. The 2026 default is uv, but each of the six wins in specific cases worth knowing. Read the full explainer →
Fix ModuleNotFoundError After pip install: The venv, PATH, and sys.path Explainer
The most common Python error after the first few lessons: pip install printed "Successfully installed requests-2.31.0" and the very next python my_script.py threw ModuleNotFoundError. Three diagnostic commands that identify the bug, five specific bug shapes (wrong env, wrong Python, not actually installed, wrong import name, editable install), and how sys.path decides what gets found. Read the full explainer →
Package Management
Installing, upgrading, and managing the dependencies that make up your project.
How to Upgrade All Pip Packages Safely (and Why pip Has No upgrade --all)
The Stack Overflow question with thousands of votes has a one-liner that bites in three real ways: editable installs, dependency conflicts, and Windows. The decade-long GitHub thread explains why pip doesn't ship an upgrade-all command, the six-step safety workflow, the new pip lock in pip 26.1, and side-by-side comparisons with pip-review, pip-tools, uv, and Poetry. Read the full explainer →
Conda vs pip vs uv: The 2026 Decision Guide (plus mamba and pixi)
Five tools compared by what they actually install: pip and uv install from PyPI; conda, mamba, and pixi install language-agnostic binary packages including native libraries, CUDA drivers, and R packages. The decision matrix by dependency type, the hybrid pattern (conda foundation plus uv inside), and how conda channels and channel priority actually work. Read the full explainer →
Project Structure
How to organize Python code so imports work the way you expect.
Importing From Another Folder in Python: src Layout, __init__.py, Editable Installs, the Five Methods
The "how do I import a file from another folder" question gets ten different answers online; most of them are tricks that break later. The five real import methods (relative, absolute, sys.path, PYTHONPATH, editable install) with a decision rule, the src vs flat layout debate, the script-vs-module trap that explains half of "but it works in the REPL" bugs, and pyproject.toml entry points. Read the full explainer →
Distribution
Getting your finished Python code into the hands of users or production servers.
Turn a Python Script Into an .exe: PyInstaller, Nuitka, BeeWare, PyOxidizer
Five Python-to-executable tools compared. PyInstaller for the default, Nuitka for speed (compiles Python to C), BeeWare Briefcase for native-looking GUI apps, PyOxidizer for embedded Python, cx_Freeze for legacy. The antivirus false-positive problem with five defenses, the --onefile vs --onedir trade-off, cross-platform build constraints (you can't build a Windows .exe on macOS), and the code-signing reality for public distribution. Read the full explainer →
Docker for Python Developers: Multi-Stage Builds, uv Integration, Size Optimization
The modern Python Dockerfile from start to finish. Four base images compared (full, slim, alpine, distroless), the multi-stage pattern that cuts image size by 80%, uv integration with cache mounts and UV_COMPILE_BYTECODE=1, the layer caching mechanics, the Alpine musl trap for numpy and pandas, docker-compose for development, and the production-ready Dockerfile template you can copy. Read the full explainer →
How the Sub-Clusters Connect
The explainers reference each other in obvious ways. The venv decision guide is the foundation for the ModuleNotFoundError fix, the PEP 668 guide, and the Docker guide because they all assume you understand what a venv is and why you'd want one. The multiple-Pythons guide connects to the Windows install guide (where the py launcher comes from) and back to the venv guide (where uv shows up as a Python version manager). The conda vs uv guide builds on the venv decision guide; if you haven't internalized why uv exists, the conda comparison won't make as much sense. The Docker guide builds on the venv guide, the import guide, and the upgrade guide all at once.
Start anywhere. Each supporting article points back here and across to the relevant siblings. After 2-3 explainers you'll have read every piece of the mental model you need to debug almost any Python environment problem from first principles, and you won't need to come back to look up commands as often.
The Bottom Line: Install uv, Make a venv, Use a Lockfile
For most Python projects in 2026, three habits cover the environment story: install uv to handle Python versions, virtual envs, and package management in one tool; pin Python with .python-version per project; commit a lockfile (uv.lock or equivalent) so collaborators and CI install the same bits you do. Where those don't fit, the ten explainers in this pillar page cover what to do instead: conda for native scientific stacks, py launcher for Windows-only setups, Docker for production deployment, PyInstaller for binary distribution. Start with the explainer that matches your current problem; come back when the next one shows up.
Skip the Environment Wars and Just Write Python
CodeGym's Python track runs Python directly in your browser through its WebIDE. No venv, no pip, no PATH gymnastics. 800+ hands-on tasks across 62 levels, an AI validator that grades every submission instantly, and an AI mentor when an error stumps you. First level free; full plan on the pricing page.
GO TO FULL VERSION