巧匠Developer Cheatsheet
Languages

Python Virtual Environments in Practice: venv, Dependency Pinning and Cross-Platform Gotchas

"Works on my machine" usually means mixed environments. This guide builds a clean flow with the stdlib venv: create, activate, pin and reproduce — plus the three frequent pitfalls: Windows activation, version drift and cross-platform dependencies.

By 巧匠 Team·8 min read·Updated 2026-08-30

Why every project needs its own environment

The global site-packages is shared by every project: project A upgrades requests to 2.32 and project B breaks in place — that is the truth behind "it worked yesterday". A virtual environment gives each project an isolated site-packages plus its own python/pip entry points; they never interfere, and deleting the directory removes everything — the simplest form of dependency governance.

python -m venv .venv        # 在项目根目录创建（建议固定叫 .venv）

Activate and deactivate: know the platform difference

Linux/macOS: `source .venv/bin/activate`; Windows PowerShell: `.venv\Scripts\Activate.ps1`; cmd: `Scripts\activate.bat`. Exit is uniformly `deactivate`. PowerShell complaining about script execution is its policy — `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` fixes it once and for all.

Point VSCode/PyCharm at the python inside .venv and the terminal auto-activates — you will rarely type these commands by hand, which is the comfortable path.

source .venv/bin/activate          # Linux / macOS
.venv\Scripts\Activate.ps1         # Windows PowerShell
deactivate                         # 退出虚拟环境

Pin dependencies: three levels of requirements.txt

① Loose (`requests`): whatever resolves, fine for prototypes; ② Range (`requests>=2.28,<3`): the usual compromise; ③ Exact pin (`requests==2.32.3`): reproducible deploys — this is what `pip freeze > requirements.txt` produces. Practical advice: express intent with ranges during development, freeze a precise lockfile for release, and let the two layers do their own jobs.

The problem with committing a raw freeze as the only dependency file: cross-platform markers bring platform-specific packages (colorama on Windows, furo on Linux), breaking teammates on the other platform — split those out or add environment markers.

requests>=2.28,<3        # 区间：表达意图
pip freeze > requirements.txt   # 锁定：可复现部署
# 跨平台标记示例：
colorama; sys_platform == "win32"

Three frequent crashes

① Creating the venv with the wrong interpreter: with multiple pythons installed, `python -m venv` may pick an old one — check `python --version` first, or be explicit with `python3.12 -m venv .venv`; ② the environment directory was moved/renamed: venv scripts hard-code absolute paths, so deleting and recreating is the cheapest fix; ③ the IDE is not running .venv: CLI works but the IDE throws ModuleNotFoundError — the interpreter is almost certainly not pointed at the venv.

python --version            # 先确认解释器
python3.12 -m venv .venv    # 必要时显式指定版本
which python                # 激活后应指向 .venv 内的 python

When to graduate to uv / poetry

The stdlib venv + pip covers single-project needs. Upgrade the toolchain when these signals appear: frequent dependency conflicts, a need for lockfile-based reproducible builds (pip-tools is the lightweight option), publishing to PyPI (poetry/hatch), or craving fast installs plus Python version management (uv). Master the standard tools first and let tools solve real pain — reversing the order only adds a layer of concepts to carry.

pip install pip-tools
pip-compile requirements.in    # 生成带锁定的 requirements.txt

One-page recap: the venv workflow

Create with `python -m venv .venv` → activate (platform-specific command) → install with `pip install` → range versions during development → `pip freeze` to lock at release → .venv goes into .gitignore, requirements.txt goes into the repo. Six steps, and environment problems stop being yours.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
echo ".venv/" >> .gitignore

More guides

Git Accident Recovery: Fix Wrong Commits, Wrong Branches and Deleted BranchesThe scariest moment in daily work is "oh no, I messed up a commit or branch". This guide gives copy-ready recovery commands for real accident scenarios, with clear safety boundaries for each.Docker Image Slimming: 5 Steps from 1.2GB to 120MBBigger images mean slower pulls, larger attack surface and higher storage cost. This guide gives 5 immediately applicable slimming steps, each with a reusable Dockerfile snippet and a verification command.Nginx 502 Bad Gateway? Locate It in 5 StepsA 502 means Nginx itself is fine but got an invalid response from the upstream (backend/proxy). This guide gives the shortest path: process → config → timeout → resources → logs.Linux Disk Full: Locate the Real Culprit with df, du and lsofA "No space left on device" error does not mean you should delete files at random. This guide walks through the full path — filesystem water level, directory drill-down, and "deleted but still held" files — plus a safe cleanup order that will not destroy data.Linux CPU at 100%: the Shortest Path from top to the Thread Stack"Restart fixes everything" is the most expensive option when CPU is pegged. This guide gives a reusable path: classify the load, pin the thread, capture what it is executing, then act — with dedicated tools for Java, Python and Go.MySQL Slow Query Tuning: Slow Log, EXPLAIN and Indexing"The database is slow" usually means a handful of slow SQL statements. This guide offers a repeatable flow: use the slow log to circle the most expensive queries, read the plan with EXPLAIN, decide whether an index pays off, and spot the most common index-defeating patterns.Redis Slowdown Playbook: Big Keys, Blocking Commands and EvictionRedis processes commands on a single thread, so one blocking hotspot slows the whole instance. This guide follows the order "memory level → big keys → blocking commands → eviction and persistence", each step with copy-ready commands.Kubernetes CrashLoopBackOff: Diagnose a Restart-Looping Pod in 5 StepsCrashLoopBackOff is not one error but a state: the container dies on start, and Kubernetes retries with backoff. This guide gives the shortest path — exit code → previous logs → probes → resources → dependencies.SSH Passwordless Login: from ssh-keygen to Permission deniedPasswordless SSH boils down to one sentence: put the public key into the remote authorized_keys. What blocks you is usually the three hidden gates — file permissions, the home directory, and SELinux. This guide covers the full setup and a step-by-step debugging path.VSCode Remote Development: Remote-SSH Setup and Connection DebuggingA weak laptop, code on an intranet server, GPUs in the cluster — Remote-SSH keeps the UI local while code and terminal run remotely, feeling native. This guide covers setup, passwordless auth, common connection failures and experience tuning.
← Back to Guides