VS Code 配置 Python 环境：新手从安装到虚拟环境完整指南

这是一篇面向第一次使用 VS Code 的读者的完整实操指南。按照顺序完成后你将能够为项目创建专用的.venv让 VS Code 选中正确的 Python 解释器并在虚拟环境中安装第三方库、运行 Python 程序。阅读目标理解 VS Code、终端、Python Interpreter 与.venv各自负责什么并完成“安装 → 终端 → Interpreter → .venv → 运行验证”的完整流程。1. 前言这篇文章要解决什么问题这篇文章不做“环境原理大全”只解决一个具体目标在VS Code中建立一个项目创建项目专用的.venv并让VS Code用它运行代码。VS Code是编辑器和开发工具Python解释器才是真正执行 .py 文件的程序。VS Code 要运行 Python必须先找到某一个具体的 python.exe。先记住一句话VS Code 负责“写、点、看”Python 解释器负责“真正执行”。2. 安装 Python打开 Python 官方 Windows 下载页选择当前稳定版。视频使用的版本较早你的安装页面显示更高版本并不代表操作错了。图 1 Python 官方 Windows 下载页面步骤1下载 Windows 安装程序并运行。安装界面若出现Add Python to PATH建议勾选。步骤2安装完成后检查版本python --version图 2 在 CMD 终端中检查 Python 版本看到类似Python 3.14.7的结果说明终端已经能找到 Python。若提示找不到命令先重新检查安装与 PATH再继续后面的操作。3. 安装 VS Code 和 Python 扩展步骤1从 VS Code 官网下载安装程序并完成安装。步骤2打开 VS Code点击左侧Extensions扩展图标。步骤3搜索Python安装发布者为Microsoft的 Python 扩展。Pylance 通常会一并安装用于补全和提示本文不展开高级设置。图 3 确认 Python 与 Pylance 的发布者为 Microsoft4. VS Code 终端PowerShell 和 CMDPowerShell 和 CMD 都是 Windows 中用来输入命令的 Shell它们本身不是 Python。VS Code 的 Terminal 只是把这些 Shell 集成到编辑器里。图 4 终端标签显示 powershell这只是当前输入命令的 Shell两者都能运行 Python。视频后面切换成 CMD不是因为 Python 必须使用 CMD而是为了统一演示并减少新手激活虚拟环境时遇到 PowerShell 执行策略提示的概率。本教程后续也统一用 CMD。步骤1打开菜单Terminal → Select Default Profile。步骤2选择Command Prompt。图 5 Select Default Profile点击 Command Prompt步骤3关闭旧终端或点击加号新建终端。新终端标签应显示cmd。图 6 新建 CMD 终端提示符通常以盘符和路径开头不要混为一谈CMD / PowerShell 回答“在哪里输入命令”系统 Python / .venv 回答“由哪个 Python 执行”。切换成 CMD不等于切换了 Python 环境。5. Python Interpreter 是什么一个类似C:\Python313\python.exe的文件就是一个具体的 Python Interpreter解释器。.py文件只是代码文本。python.exe读取并执行这些代码。Python: Select Interpreter的本质是告诉 VS Code这个项目以后用哪个 python.exe。最重要的判断当运行结果、安装位置或 import 出现疑问时先看 VS Code 选中了哪个解释器。6. 为什么会有多个 Python 版本Python 会持续更新因此电脑中可能同时存在 3.10、3.11、3.12、3.13、3.14。每安装一个版本本质上就多了一套解释器。不同版本在功能、性能、Bug 修复和第三方库兼容性上会有差异。正因为可能有多个 PythonVS Code 才需要明确选择 Interpreter。下图同时出现了多个系统 Python以及项目里的 .venv。图 7 解释器列表系统 Python 与项目 .venv 可以同时存在7. 为什么要使用 .venv假设项目 A 需要 requests 和 matplotlib项目 B 以后需要另一组库或不同版本。如果都装进系统 Python项目之间容易互相影响。MyProject/ ├─ .venv/ ├─ main.py └─ ...可以把.venv简单理解为这个项目专用的一套Python运行环境。它有自己的解释器、pip 和第三方库。8. .venv 和系统 Python 的关系假设电脑已经安装C:\Python313\python.exe。在项目目录执行python -m venv .venv它不是凭空再下载安装一套 Python而是以当前执行这条命令的基础 Python 为起点创建项目环境。视频 P4 使用python3.10 -m venv .venv来明确版本这种写法在普通 Windows 环境中不一定可用。本教程先用python --version确认版本再使用更通用的python -m venv .venv。系统PythonC:\Python313\python.exe↓python -m venv .venv项目中的.venv↓自己的python 自己的pip 自己的第三方库图 8 系统 Python 创建项目 .venv 的关系9. .venv 的作用范围D:\CODE\python\crm ├─ .venv/ ├─ main.py ├─ test.py └─ data/技术上.venv 并没有“只能管理所在文件夹”的硬边界它本质上是一套解释器和库环境。但项目开发通常约定一个项目文件夹对应一个 .venv.venv 放在项目根目录项目内的代码统一使用这套环境。新手的正确理解含有 .venv 的这个大文件夹就是一个项目而 .venv 是这个项目使用的 Python 环境。10. 创建 .venv步骤1创建项目文件夹例如MyProject再用 VS Code 的File → Open Folder打开它。步骤2在项目根目录新建main.py。创建前资源管理器里还没有 .venv。创建前创建后图 9 创建前后项目根目录新增 .venv 文件夹步骤3打开 CMD 终端确认提示符所在路径就是项目根目录然后执行步骤4等待命令结束。Explorer 中出现.venv文件夹即创建成功。不要手动编辑里面的文件。11. 让 VS Code 使用 .venv步骤1按Ctrl Shift P打开命令面板。步骤2搜索并点击Python: Select Interpreter。步骤3选择路径中包含.venv\Scripts\python.exe的项目解释器。图 10 选择带有 .venv\Scripts\python.exe 的工作区解释器这一步是在告诉 VS Code以后这个项目运行 Python 时优先使用项目自己的虚拟环境而不是 C 盘中的系统 Python。步骤4新建一个终端。若提示符前出现(.venv)说明 VS Code 已自动激活该环境。图 11 CMD 提示符前出现 (.venv)如果想做一次更直接的确认可执行python -c import sys; print(sys.executable)图 12 输出路径指向项目的 .venv\Scripts\python.exe12. 安装一个第三方库并运行程序确认终端处于 (.venv) 后安装视频 P4 使用的 requestspython -m pip install requests这里用python -m pip可以让当前这个 python.exe 调用自己的 pip减少“包装到了另一个 Python”这种常见混乱。图 13 出现 Successfully installed 表示 requests 已装入当前 .venv在main.py中输入import requests print(Python environment is ready!) print(requests version:, requests.__version__)保存文件后可点击编辑器右上角的Run Python File也可以在终端执行python main.py。看到欢迎文字和 requests 版本号就说明解释器选择、安装与运行三步都连通了。图 14 在 .venv 中运行 main.py 成功若出现ModuleNotFoundError先确认终端前有 (.venv)再确认 VS Code 选中 .venv\Scripts\python.exe最后重新执行 python -m pip install requests。本文不展开更复杂排错。13. 一张图总结 VS Code、CMD、Interpreter 和 .venvVS Code编辑代码、集成终端、记住项目解释器Shell 层Python 环境层CMD / PowerShell决定“在哪里输入命令”系统 Python / .venv决定“由哪个 Python 执行”Python: Select Interpreter↓选择MyProject\.venv\Scripts\python.exeRun Python File /python main.py→ .venv 的解释器执行代码 → 从 .venv 中寻找 requests图 15 Shell 与 Python 环境是两个层面切换 CMD 不等于切换解释器完成后的标准流程以后新建 Python 项目可以重复这条短流程打开项目文件夹 → 新建 CMD Terminal → python -m venv .venv → Python: Select Interpreter → 选择 .venv\Scripts\python.exe → python -m pip install 需要的库 → Run Python File简短参考资料Python 官方在 Windows 上使用 PythonPython 官方venvVS Code 官方Python environmentsVS Code 官方Integrated Terminalpip 官方User Guide总结配置 VS Code 的关键并不是“安装了多少工具”而是始终确认两件事命令在哪个 Shell 中输入以及项目最终由哪个python.exe执行。为每个项目建立独立的.venv并在 VS Code 中选择对应解释器可以显著减少版本冲突和“库明明装了却无法导入”的问题。