python 命令找不到 command not found 速查：PATH、python3 与 venv 激活
更新时间：2026-10-24。FAQ 速查页，面向新机器或新终端里敲
python换来一行command not found的同学。这个报错的本质是 shell 的查找机制：你敲的命令名，shell 只在 PATH 环境变量列出的目录里逐个找同名可执行文件，全部落空就报 not found——它说的是「没找到这个名字」，而不是「这台机器没装 Python」。病因收敛在六根轴上：机器确实没装解释器；装了但安装目录没进 PATH（Windows 安装时没勾 Add to PATH 是经典剧本）；系统只有python3没有python这个名字（绝大多数现代 Linux 发行版的现状）；Windows 上该走py启动器而不是 python；装了 venv 但当前终端没激活，找到的是系统版或干脆落空；以及多版本并存时 PATH 顺序决定先找到谁、找到的不是你要的那个。顺一遍基本必中。如果命令能跑但第三方包导不进来，转 ModuleNotFoundError 速查。
本文要回答的问题
command not found是 Python 没装，还是 PATH 没配？- 为什么
python找不到、python3却能跑？ - Windows 上 python、py、python3 三个名字各是什么来路？
- venv 建好了，为什么 pip 装包还是装到系统里去了？
- 一台机器多个 Python 版本，怎么确认当前用的是哪个？
一、报错原文与典型现象
报错由 shell（bash/zsh/cmd/PowerShell）发出，与 Python 本身无关，路径以 /proj/demo 占位：
$ python /proj/demo/app.py
bash: python: command not found# zsh 的措辞略不同
zsh: command not found: pip
# Windows cmd 的措辞
'python' 不是内部或外部命令，也不是可运行的程序# 换 python3 就能跑——名字问题不是安装问题
$ python3 /proj/demo/app.py
hello读现象抓一条铁律：报错来自 shell 而非 Python，说明解释器压根没被启动，排查方向只有两个——「这个名字的可执行文件存在吗」和「它所在的目录在 PATH 里吗」。先用 python3 --version 或 py --version 试相邻名字，能跑就立刻排除「没装」，把范围缩到名字与 PATH。
二、病因处置速查表
| 报错现象 / 场景 | 可能原因 | 快速验证 | 处置 |
|---|---|---|---|
| python command not found，python3 能跑 | 系统只注册 python3 这个名字 | python3 --version 验证 | 改用 python3，或建 python 别名/软链 |
| python 与 python3 都找不到 | 真没装解释器 | 包管理器查询安装记录 | 用系统包管理器或官网安装包装上 |
| 装了但新开终端找不到 | 安装目录未进 PATH | echo $PATH 查目录列表 | 把安装目录写入 shell 配置文件 PATH |
| Windows 装完 cmd 仍找不到 | 安装时没勾 Add python to PATH | 重新运行安装器看勾选项 | 安装器 Modify 勾选补 PATH，或改用 py |
| venv 里 pip 装到了系统环境 | 当前终端没激活 venv | which pip 看指向哪 | 先执行 activate 再操作，或直接用 venv 内路径 |
| 找到的版本不是预期的 | 多版本并存，PATH 顺序决定胜负 | which -a python3 列全部命中 | 调 PATH 顺序或用版本管理工具切换 |
三、排查决策图
下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。
读这张图抓分水岭：第一步永远是「试相邻名字」——python3 或 py 能跑，机器上就有解释器，问题只剩名字与 PATH；全落空才是真没装。能跑但版本不对则进入 venv 激活与多版本顺序那条支路，三种病因的修法互不通用。
四、逐条排查展开
command not found 是 shell 的话，不是 Python 的话。 shell 解析命令时按 PATH 里的目录顺序找同名可执行文件，找不到才报这句话。这意味着两种截然不同的现实都产生同一报错：机器没装 Python，和 Python 安安静静躺在某个目录里但那个目录不在 PATH 中。区分方法就是换名字试与直接查文件系统：python3 --version、py --version 各敲一遍，再看常见安装位置（Linux 的 /usr/bin、macOS 的 /usr/local/bin 或框架目录、Windows 的用户目录下 Python 安装夹）。
python3 能跑、python 不能跑是现代系统的常态。 多数 Linux 发行版与 macOS 早就不再提供名为 python 的命令，只注册 python3，目的是和历史上的 Python 2 划清界限。处置三选一，按场景挑：脚本和文档统一改用 python3 与 pip3（最稳，无侵入）；给 shell 配置加别名 alias python=python3（只影响交互终端）；或用发行版的 python-is-python3 类兼容包建软链（影响全系统，服务器上先评估）。CI 与脚本里建议永远写 python3，不赌目标机器有没有别名。
Windows 三条路：python、py、商店占位。 Windows 安装器默认不勾「Add python to PATH」，装完 cmd 里敲 python 就报「不是内部或外部命令」。正解有两个：重跑安装器选 Modify 把 PATH 勾上；或者干脆用随安装器一起装上的 py 启动器——它不靠 PATH，还能用 py -3.11 这样的参数在多个已装版本间点名切换，多版本共存的 Windows 机器上 py 启动器是官方推荐姿势。另一个坑：从没装过 Python 的 Windows 上敲 python 会弹应用商店页，那个商店占位入口有时还排在 PATH 前面截胡，需要在系统设置的应用执行别名里关掉。
venv 建了不等于在用，激活是当前终端的事。 venv 的激活脚本做的事很朴素：把 venv 的 bin（Windows 是 Scripts）目录插到 PATH 最前面，于是 python 和 pip 都先命中 venv 内的副本。没激活的终端里，pip 装包装进系统环境，运行时 venv 里自然找不到——「装过了还 ModuleNotFoundError」的头号剧本。验证用 which pip（Windows 用 where pip）：指向 venv 内路径才算激活成功。写自动化脚本时更稳的做法是不依赖激活，直接调用 venv 内的绝对路径，如 /proj/demo/.venv/bin/pip install -r requirements.txt，这样 cron 与 CI 里也不会踩「非交互终端没激活」的坑。
多版本并存时 PATH 顺序就是真相。 which -a python3（Windows 用 where python）把 PATH 里所有命中按优先级列出来，第一个就是实际被执行的那个。版本不对就两条路：调整 PATH 里目录的先后顺序；或者上版本管理工具（pyenv、uv 等）用 shim 机制显式切换，项目级还能用 .python-version 文件钉死版本。团队协作场景推荐后者——把版本写进仓库，比约定「大家把 PATH 配成一样」可靠得多。
新开终端又找不到：配置写错了文件。 手动 export PATH=... 只对当前终端生效，关掉就丢。要持久化得写进 shell 的启动文件（bash 是 ~/.bashrc 或 ~/.bash_profile，zsh 是 ~/.zshrc），写完 source 一下或开新终端验证。macOS 用户注意默认 shell 早已是 zsh，改 bash 的配置文件不生效是高频自坑。
五、规范做法与预防
- 脚本与文档统一写 python3：不依赖目标机器有没有 python 别名，跨发行版最稳。
- 新机器环境清单入库：装解释器、补 PATH、关商店占位（Windows）三步写成装机脚本，不凭记忆手点。
- 项目一律 venv 隔离：仓库 README 写明建 venv、激活、装依赖三条命令；自动化脚本用 venv 内绝对路径不依赖激活。
- 多版本机器上版本管理工具：版本钉进
.python-version类文件随仓库走，不靠人肉对齐 PATH。 - CI 镜像预装固定版本：流水线镜像里解释器版本固定，steps 里先跑
python3 --version落日志便于归因。 - 排查先问 shell 再问 Python：command not found 阶段解释器还没启动，别去翻 Python 的文档，先查 PATH 与安装事实。
这一篇在知识体系里的位置
本篇是 Python 排错速查簇的「环境入口」篇，定位解释器与 PATH 问题：命令能跑但包导不进来看 ModuleNotFoundError 速查；装包过程本身失败看 pip install 失败速查；解释器版本与依赖要求不符看 Python 版本不匹配速查。「先试相邻名字区分没装与没在 PATH、能跑再查 venv 激活与版本顺序」这条主线对一切命令找不到类报错通用。
一句话总结
command not found 是 shell 在 PATH 里找不到这个名字，不等于机器没装 Python：先试 python3 与 py 相邻名字，能跑就是名字或 PATH 问题——现代系统只有 python3 是常态，脚本统一写 python3 最稳；全落空才用包装。Windows 安装没勾 Add to PATH 就重跑安装器补勾或改用 py 启动器，商店占位别名记得关。venv 建了不激活等于没用，which pip 指向 venv 内才算数，自动化脚本直接调 venv 内绝对路径。多版本机器 which -a 看 PATH 顺序，版本钉进仓库文件随代码走，命令找不到从此是查表题。