VS Code运行Python报错“'Python'不是内部或外部命令”的解决方法

一、报错成因：VS Code 终端与系统 PATH 的关联机制

初次使用 VS Code 的开发者常产生一个误区：认为已经在 VS Code 左侧安装了 Python 插件，或者在编辑器右下角选好了解释器，VS Code 就能自动在终端中识别 python 命令。

事实上，VS Code 底部集成的“终端”（Terminal）本质上是直接托管系统本地的命令行外壳（PowerShell 或 CMD）。当你在终端输入 python test.py 并回车时，命令的解析权完全交给 Windows 系统的 Shell，与 VS Code 插件的设置相互独立。

Windows 收到指令后，会依次在“当前工作目录”以及“系统环境变量 Path 所包含的目录”中寻找名为 python.exe、python.bat 或 python.cmd 的文件。如果遍历了 Path 中的所有路径均未找到对应文件，终端便会抛出“'Python'不是内部或外部命令”的错误提示。

二、排查第一步：核实本地安装并获取 Python 真实路径

在进行任何配置之前，首先需要明确：电脑上到底有没有安装 Python？安装到了哪个文件夹？

1. 检索常见的 Python 安装路径

Windows 官方安装包默认根据安装选项不同，将 Python 存放于以下两处常见位置之一（以 Python 3.11 为例，其中 <用户名> 为你的实际 Windows 登录账号名）：

• 仅当前用户（默认推荐选项）：
  C:\Users\<用户名>\AppData\Local\Programs\Python\Python311
• 为所有用户安装（勾选了 Install for all users）：
  C:\Program Files\Python311 或 C:\Program Files (x86)\Python311

2. 若尚未安装 Python

若在上述路径及全盘搜索中均找不到任何 Python 安装痕迹，说明此前并未安装运行环境。需前往 Python 官方网站（python.org）下载对应的 Windows 64-bit 安装包。

在启动安装程序的第一屏界面上，务必先勾选底部的“Add python.exe to PATH”，然后再点击“Install Now”。勾选此选项后，安装器会自动向系统写入环境变量，省去后续的手动配置步骤。

三、排查第二步：手动将 Python 与 Scripts 添加至系统 Path

如果本地已经存在 Python 安装目录，但当时安装时遗漏了勾选环境变量选项，可以通过 Windows 系统属性手动将其补齐。

1. 需要加入 Path 的两个关键路径

配置环境变量时，必须同时添加两个目录，缺一不可：

1. Python 主程序目录：即 python.exe 所在的根目录，例如 C:\Users\Administrator\AppData\Local\Programs\Python\Python311\。此目录用于响应 python 命令。
2. Scripts 脚本目录：即主程序目录下的 Scripts 文件夹，例如 C:\Users\Administrator\AppData\Local\Programs\Python\Python311\Scripts\。此目录用于响应 pip 包管理工具以及各类第三方命令行工具。

2. 具体操作步骤详述

1. 按键盘上的 Win + R 键调出运行对话框，输入 sysdm.cpl 并按回车，快速打开“系统属性”。
2. 在弹出的窗口上方切换到“高级”选项卡，然后点击右下角的“环境变量”按钮。
3. 在下方的“系统变量”区域中找到名为 Path 的行（如果无系统管理员权限，也可在上方“用户变量”的 Path 中修改），选中后点击“编辑”。
4. 在弹出的列表右侧点击“新建”，将本地查找到的 Python 安装根目录粘贴进去。
5. 再次点击“新建”，将 Python 安装目录下的 Scripts 完整路径粘贴进去。
6. 依次点击各个弹窗的“确定”按钮关闭窗口。必须连续点击确定直到所有配置对话框退出，修改才会被真正写入系统注册表。

四、关键动作：彻底重启 VS Code 以刷新环境变量快照

许多开发者在配置完系统环境变量后，立刻切回 VS Code 终端再次敲击 python，却发现仍然提示同样的错误。

这是因为 操作系统的环境变量在应用程序启动时被一次性读取并加载为内存快照。VS Code 主进程及其内置的终端进程是在配置环境变量之前就已经启动的，它们依然保留着旧版的环境变量副本，根本无法感知系统 Path 的改动。

刷新环境变量的具体方式：

• 最彻底的方法：直接点击 VS Code 右上角的关闭按钮完全退出软件，甚至在任务管理器中确认无遗留的 Code.exe 进程，然后重新启动 VS Code。
• 免重启窗口的方法：在 VS Code 底部终端面板中，点击终端下拉列表旁边的“垃圾桶”图标，彻底销毁（Kill）当前的终端实例；随后点击“+”号新建一个终端，此时新建的 Shell 也会尝试从系统中加载最新的环境变量。

五、特殊干扰：排除 Windows“应用执行别名”的重定向拦截

在 Windows 10 与 Windows 11 系统中，即使环境变量已经正确添加，仍可能遇到一种特殊表现：在终端输入 python 后，不仅没有运行代码，反而自动弹出了微软应用商店（Microsoft Store）的 Python 下载页面，或者提示拒绝访问。

这是因为 Windows 系统默认开启了“应用执行别名”（App Execution Aliases）。系统在 %LOCALAPPDATA%\Microsoft\WindowsApps 目录下放置了一个 0 字节的 python.exe 快捷方式，其目的是引导未安装 Python 的用户前往应用商店下载。当该路径在 Path 中的顺序靠前时，它会优先拦截你的调用。

彻底关闭应用别名的操作方法：

1. 按快捷键 Win + I 打开 Windows“设置”。
2. 点击进入“应用” -> “高级应用设置”（部分版本为“应用和功能”）。
3. 找到并点击“应用执行别名”（App execution aliases）。
4. 在列表中向下滑动，找到针对 “应用安装程序 (python.exe)” 和 “应用安装程序 (python3.exe)” 的开关，将其全部切换为“关”。

关闭别名后，系统在检索命令时便不会再受到空壳文件的误导，而是直接匹配你手动配置的真实 Python 安装路径。

六、验证结果与 VS Code 解释器配置

完成上述配置并重启 VS Code 后，需要按照以下步骤进行结果验证与编辑器关联。

1. 命令行验证输出

在 VS Code 顶部菜单栏点击“终端” -> “新建终端”，在打开的命令行中输入以下命令进行测试：

python --version
pip --version

预期输出结果（示例）：

Python 3.11.8
pip 24.0 from C:\Users\Username\AppData\Local\Programs\Python\Python311\Lib\site-packages\pip (python 3.11)

如果终端能够正确返回版本号和对应路径，说明操作系统层面的路径解析已经完全畅通。

2. 在 VS Code 中选定 Python 解释器

虽然终端已经可以识别命令，为了确保编辑器能正常提供语法检查和代码调试功能，还需要为 VS Code 指定正确的解释器：

1. 在 VS Code 界面中按下 Ctrl + Shift + P 打开命令面板。
2. 输入并选择 Python: Select Interpreter（选择解释器）。
3. 在弹出的推荐列表中，选择刚刚配置好的带有版本号的 Python 解释器（例如 Python 3.11.8 ('base')）。
4. 如果列表中未显示，可点击“Enter interpreter path...”（输入解释器路径），手动浏览选择 python.exe 文件。

七、总结排查路线与速查清单

遇到该问题时，可对照以下决策树与核对清单依次排查，定位卡点：

按照上述路径逐项核实后，VS Code 终端便能稳定识别 Python 运行环境，后续无论是直接运行脚本、使用 pip install 安装第三方扩展包，还是使用调试器进行单步调试，均能正常执行。