准备工作

很多人第一次学 Python，代码还没来得及写，就先被环境问题拦住了：教程让你输入 python，电脑却说找不到命令；编辑器右上角明明有“运行”按钮，点下去却跑了另一个版本；刚刚安装好的库，换一个窗口又提示不存在。碰到这些情况，问题往往不在代码，而在于我们还没有分清“谁在执行代码”“命令发给了谁”“包装到了哪里”。

这一章不追求一次装好所有工具。我们的目标更实际：准备一套能解释、能验证、出错后也知道从哪里查起的 Python 开发环境。等你能在终端里确认解释器、进入和退出交互环境、运行一个脚本，再给项目建好虚拟环境，后面的学习就不会总被工具问题打断。

先认清手里的几样工具

刚开始最容易出现的误会，是把 Python、编辑器和终端当成同一个东西。其实一次最普通的“运行代码”，至少有四个角色参与。

解释器负责真正执行代码

我们写下的 print("你好") 只是文本。Python 解释器会读取这段文本，检查语法，再按照语言规则执行。安装 Python，核心就是把这个解释器装到电脑上。解释器通常是名为 python、python3 或由 Windows 上的 py 命令找到的程序。

所以，“电脑里有一个 .py 文件”不等于“电脑能运行 Python”。.py 只说明文件里保存的是 Python 源代码；真正干活的是你调用的解释器。

终端负责把命令交给程序

终端窗口里运行着一个命令行环境，也常被叫作 shell。你在这里输入 cd、dir、ls、python，shell 会先判断第一个词代表哪个程序或内置命令，再把后面的内容当作参数交过去。

例如下面这条命令不是一整块神秘咒语：

python hello.py

shell 找到名为 python 的解释器，然后把 hello.py 这个文件名交给它。解释器读取文件并执行。要是 shell 根本找不到 python，代码文件写得再正确也不会开始运行。

编辑器负责写文件和帮助检查

编辑器会提供语法高亮、自动缩进、代码补全和错误提示，但它通常不自带你项目所需的 Python 环境。编辑器里的“运行”按钮，背后仍然是在调用某个解释器。选错解释器，就会出现“终端里能运行，编辑器里不能运行”或者反过来的情况。

第一章不用追求插件最多的编辑器。能明确选择 Python 解释器、能打开项目文件夹、能显示内置终端，就足够完成学习。如果你暂时不想配置复杂工具，官方安装中常见的 IDLE 也能写文件、运行脚本和进入交互环境。

项目目录把一次练习圈在一起

项目目录就是保存本次代码、虚拟环境和其他资料的文件夹。我们后面会创建一个 python-start 目录。每次开始练习，先进入这个目录，再运行命令。这样做看起来只是整理文件，实际上还能减少“终端正在 A 目录，脚本却放在 B 目录”的低级错误。

你可以先记住这条执行链：

你输入命令 → 终端查找解释器 → 解释器读取 .py 文件 → 屏幕显示结果或错误

终端负责找到程序，解释器负责读取并执行脚本；排错时也可以沿这条链逐项检查。

后面遇到问题，我们也沿着这条链倒着查，不靠反复卸载重装碰运气。

选择适合学习的 Python 版本

打开下载页时，你可能会看见多个 3.x 版本、测试版、不同处理器架构，甚至源码压缩包。新手没必要把它们全研究一遍，先按一个稳妥原则选择：安装官网当前提供的稳定版 Python 3，避开名称里带 alpha、beta 或 release candidate 的预发布版本。

稳定版中的“小版本号”也可能不同，例如一台电脑装的是 3.x，另一台是相邻的 3.y。本课程的基础代码通常都能运行。以后参与已有项目时，项目可能明确要求某个版本，那时应服从项目要求，而不是擅自追新。

别凭图标判断版本，用命令确认

安装完成后，我们真正关心的是终端会启动哪个解释器。版本检查不会进入 Python，也不会执行脚本：

python --version

在 macOS 或 Linux 上，系统更常提供 python3：

python3 --version

Windows 还可以使用 Python 安装管理器提供的 py 命令：

py --version
py list

只要输出以 Python 3. 开头，就说明我们找到了 Python 3。不要照抄示例中的具体尾号来判断成败；补丁版本会更新，你本机显示得更新很正常。

处理器架构只在下载安装包时需要留意

普通的 64 位 Windows 电脑通常选择 64-bit；使用 Apple 芯片的 Mac 应选择适合 Apple silicon 或通用架构的安装包。系统如果能自动推荐下载项，跟随推荐即可。32 位包、ARM64 包和源码包都有特定用途，但不适合拿来“试试看”。选错架构常见结果不是代码变慢一点，而是安装器直接拒绝、第三方包没有匹配文件，或者系统根本无法启动解释器。

在不同系统上安装与验证

安装步骤会随操作系统和 Python 版本更新，界面文字也会变化。我们不死记某一张安装截图，而是抓住三件事：从可信的官方入口获取安装程序，安装后开一个新的终端，最后用命令验证版本与解释器位置。

Windows：先让命令稳定可用

Windows 通常不把 Python 当作系统组件预装。当前官方方案会提供 Python 安装管理器，你可以从 Python 官方下载入口或 Microsoft Store 安装。安装完成后，打开一个新的 PowerShell 或 Windows Terminal，依次检查：

python --version
py --version
py list

py list 能帮助你看见安装管理器知道哪些运行时。只有一个学习版本时，不必做复杂的默认版本配置；能稳定执行 python 或 py 即可。

如果你使用较早版本页面里的传统安装器，可能会看到把 Python 加入 PATH 的选项。PATH 是 shell 查找程序时依次搜索的一组目录。勾选后，终端更容易找到 python.exe 和脚本目录。不过，即使你错过了这个选项，也先别急着重装：Windows 的安装管理器或 py 命令可能仍能正确找到解释器。

验证“它实际在哪”可以使用：

Get-Command python
Get-Command py

如果 python 打开的是应用商店提示，py 却能正常显示 Python 3 版本，学习时先使用 py 完成后续命令，再检查 Windows 的“应用执行别名”和用户 PATH。不要同时装很多来源不同的 Python 来修一个查找问题，那通常只会让选择关系更乱。

macOS：不要依赖系统自带命令的猜测

macOS 上先打开“终端”，检查：

python3 --version
command -v python3

第二条命令会显示 shell 找到的解释器路径。若没有可用版本，可以使用 Python 官方的 macOS 安装包。官方安装完成后，应用程序目录中通常会出现对应版本的 Python 文件夹，其中包含 IDLE、Python Launcher，以及用于完成证书安装的命令文件。若之后通过 Python 程序访问 HTTPS 时持续遇到证书校验错误，应先确认官方安装包附带的证书步骤是否完成。

macOS 上教程常写 python3 而不是 python，原因很简单：不同系统对无版本号的 python 如何处理并不完全一致。进入虚拟环境后，python 会稳定指向该环境里的解释器；进入环境之前，使用本机验证过的 python3 更省心。

Linux：把系统 Python 和学习项目分开

多数 Linux 发行版会提供 Python 3，因为系统工具本身可能依赖它。先检查：

python3 --version
command -v python3

如果缺少 Python、pip 或 venv，优先使用当前发行版的包管理器安装对应组件。不同发行版的软件包名称略有差异，应以系统给出的提示和仓库信息为准。

这里有一条很重要的边界：不要为了跟课程里的某个版本号完全一致，就删除、覆盖或手动替换 /usr/bin/python3；也不要看到权限错误就直接在 pip 前加 sudo。发行版可能把这套 Python 当作系统的一部分，随意更改会把系统工具一起弄坏。学习项目需要第三方包时，我们马上会用虚拟环境把它隔离开。

一些 Linux 会在全局安装包时报告环境由外部管理。这个提示不是故障，而是系统明确告诉你：全局 Python 归系统包管理器维护。正确处理方式通常是建立虚拟环境，不是强行绕过保护。

用同一组命令做验收

无论你用什么系统，安装结束后都建议新开一个终端。旧终端可能还保留着安装前的 PATH，继续在旧窗口测试，会让你误以为安装没有生效。

Windows 可以执行：

py --version
py -c "import sys; print(sys.executable)"
py -m pip --version

macOS 与 Linux 可以执行：

python3 --version
python3 -c "import sys; print(sys.executable)"
python3 -m pip --version

三个平台的安装入口不同，但验收目标一致：确认版本、解释器位置，以及这个解释器对应的 pip。

第一条确认版本，第二条打印解释器的真实路径，第三条检查这个解释器对应的 pip。这里故意使用 python -m pip 这种形式，因为它明确表达“让眼前这个 Python 去运行 pip 模块”，比单独输入 pip 更不容易串到另一个环境。

python3 -m ensurepip --default-pip

py -m ensurepip --default-pip

分清终端提示符和 Python 提示符

新手经常把命令输对了地方却输错了。终端和 Python 交互环境都允许你敲字，看起来很像，但它们理解的是两种语言。

终端提示符接受系统命令

PowerShell 的提示符可能以 PS C:\...> 开头，macOS 与 Linux 的终端常以 % 或 $ 结尾。教程代码块里的 $、% 和 PS> 往往只是提示符示意，不是命令内容。

下面这些要在终端里执行：

python3 --version
cd python-start
python3 hello.py

Windows 则常写成：

py --version
cd python-start
py hello.py

>>> 后面只接受 Python 代码

在终端输入 python3、python 或 py 后，如果看见 >>>，说明解释器已经进入交互模式，也叫 REPL。这个缩写表达的过程很直白：读取一段输入、执行、显示结果，然后继续等待。

>>> 21 * 2
42
>>> message = "环境准备好了"
>>> print(message)
环境准备好了

赋值语句没有自动输出，所以输入 message = ... 后直接出现下一个 >>> 是正常的。表达式 21 * 2 会显示它的值，而脚本运行时若想把结果展示给用户，通常应明确调用 print()。

如果你在 >>> 后输入 python3 --version，Python 会把它当成 Python 语法来分析，接着给出 NameError 或 SyntaxError。这并不表示 Python 没装好，只表示命令放错了地方。先退出交互环境，再回到终端：

>>> exit()

macOS 和 Linux 也可按 Ctrl+D 发送输入结束；Windows 通常使用 Ctrl+Z 后按回车。初学阶段记住 exit() 就够了。

输入前先辨认提示符：系统命令留在终端，Python 表达式交给交互环境。

... 是在等你把代码补完

输入以冒号结尾的复合语句后，提示符会变成 ...：

>>> for name in ["小林", "阿青"]:
...     print("你好，" + name)
...
你好，小林
你好，阿青

这不是卡死。解释器知道 for 语句还缺少缩进代码块，所以继续等待。输入完整代码后，再敲一个空行，解释器才执行整段。要是输入乱了，可以按 Ctrl+C 取消当前这段，重新开始。

REPL 和脚本各有合适的场景

想快速算一个表达式、试一个函数、确认某种语法时，REPL 很方便。代码超过几行、以后还要修改或再次运行时，就应该保存成脚本。REPL 的输入通常不会自动变成项目文件，关掉窗口后也不适合作为正式成果保存。

解释器还有几种常见调用形式：

python3 hello.py
python3 -c "print(6 * 7)"
python3 -m pip --version

第一条执行文件，第二条直接执行引号中的短代码，第三条按照模块名找到 pip 并运行。我们平时主要使用“脚本文件”和 -m 两种形式。

配好编辑器，但别让按钮遮住真相

编辑器能明显改善体验，不过第一天最值得配置的只有三项：打开整个项目目录、选择正确解释器、确认文件以纯文本和 UTF-8 保存。主题颜色、字体和几十个插件都可以以后再说。

打开目录，不要只打开孤零零的文件

如果只双击一个 .py 文件，编辑器未必知道它属于哪个项目，内置终端也可能从别的目录启动。更稳妥的做法是用“打开文件夹”打开 python-start。这样文件树、终端工作目录和解释器配置更容易保持一致。

明确选择解释器

支持 Python 的编辑器通常会显示当前解释器的版本或路径。创建虚拟环境后，应把解释器切换到项目里的 .venv：

Windows: .venv\Scripts\python.exe
macOS / Linux: .venv/bin/python

如果编辑器提示安装 Python 扩展，可以安装官方或编辑器推荐的语言支持扩展，但要明白扩展不等于 Python 解释器。扩展装好了、电脑没装解释器，代码仍然跑不起来。

留心文件名和扩展名

第一个文件可以叫 hello.py。不要叫 hello.py.txt，也不要只凭文件图标判断扩展名。Windows 若隐藏已知文件扩展名，建议在文件资源管理器中打开扩展名显示。

初学时也不要把自己的文件命名为 random.py、json.py、time.py、venv.py 或 pip.py。这些名称与标准库或工具模块冲突。以后写 import random 时，Python 可能先导入你自己的同名文件，报错会显得毫无来由。

编辑器运行和终端运行要互相验证

按钮运行失败时，先在编辑器内置终端执行同一个脚本。反过来，按钮能运行而外部终端不行，也要检查两边解释器路径。可以临时运行：

import sys
 
print(sys.executable)

它会告诉你当前脚本究竟由哪个解释器执行。路径不是你预期的 .venv 时，问题就在解释器选择，不在 import 语句。

创建项目并运行第一段程序

现在把前面的部件真正接起来。我们会创建一个单独目录，写一个脚本，再从这个目录运行它。

建立并进入项目目录

在 Windows PowerShell 中：

mkdir python-start
cd python-start
Get-Location

在 macOS 或 Linux 中：

mkdir python-start
cd python-start
pwd

mkdir 创建目录，cd 切换当前目录，最后一条显示当前位置。教程里常见的“找不到文件”有一大半是终端位置不对，所以不要跳过位置检查。

接着用编辑器打开这个目录，新建 hello.py。输入：

name = "小虎"
course = "Python"
 
print("你好，我是" + name)
print("我已经成功运行第一段 " + course + " 程序")

这里先不急着讲变量的全部规则。你只需看出：前两行把文字分别交给 name 和 course，后两行使用它们拼出要显示的句子。保存文件后回到终端。

Windows 执行：

py hello.py

macOS 或 Linux 执行：

python3 hello.py

预期输出是：

你好，我是小虎
我已经成功运行第一段 Python 程序

第一次运行脚本时，把目录、保存状态、解释器和输出连成一个可以逐步验证的闭环。

运行成功时，终端可能只安静地回到提示符

如果脚本里只有赋值，没有 print()，运行后不显示内容是正常的。解释器不会自动把脚本中每个表达式都展示出来。REPL 会回显表达式的值，是为了方便探索；脚本需要明确决定哪些信息要输出。

修改后记得保存

你把文字改成自己的名字，运行结果却没变化，常见原因不是 Python 缓存了文件，而是编辑器里的修改尚未保存。先看标签页上是否有未保存标记，保存后再运行。

文件名含空格时需要引号

我们建议项目和脚本使用短横线、下划线或简单英文名，能少掉很多转义问题。若路径已经含空格，shell 需要知道它是一个整体：

python3 "my scripts/hello.py"

Windows 同理：

py "my scripts\hello.py"

不过不要把所有错误都归咎于中文路径或空格。先读错误里显示的实际路径，确认文件是否真的在那里。

给每个项目一个虚拟环境

写完第一个脚本后，很多教程会马上让你安装第三方库。真正容易踩坑的地方也从这里开始：项目 A 需要某个库的旧版本，项目 B 需要新版本；你在全局环境升级一次，A 就可能跟着坏掉。

虚拟环境解决的是“项目之间互不干扰”。它在项目目录里准备一套独立的解释器入口和包安装位置。进入环境后，python 和 pip 会优先指向这一套环境，而不是到处修改系统 Python。

每个项目使用自己的虚拟环境，第三方包各自存放，升级一个项目不会牵连另一个项目。

创建 .venv

先确认终端位于 python-start。Windows 执行：

py -m venv .venv

macOS 或 Linux 执行：

python3 -m venv .venv

命令可能安静地结束，这是正常的。项目里会出现 .venv 目录。开头的点表示它通常被当作项目内部的隐藏目录；这个名字是常见约定，不是硬性语法。

venv 会使用执行创建命令的那个 Python 作为基础，所以创建前的版本检查很重要。若版本选错了，删除并重新创建项目虚拟环境通常比在里面硬改更可靠。

激活环境

Windows PowerShell：

.\.venv\Scripts\Activate.ps1

Windows 命令提示符：

.venv\Scripts\activate.bat

macOS 或 Linux 的 bash、zsh：

source .venv/bin/activate

成功后，提示符前通常会出现 (.venv)。它只是醒目的提示，不是唯一证据。再检查一次：

python -c "import sys; print(sys.executable)"
python -m pip --version

两条输出的路径都应该落在当前项目的 .venv 中。

激活的本质，是把虚拟环境的可执行目录临时放到当前 shell 的查找顺序前面。它只影响当前终端会话。你新开一个终端，通常需要再次激活；关闭终端也不会删除环境。

不激活也能使用，只是命令更长

激活并非运行虚拟环境的必要条件。你可以直接调用里面的解释器：

.venv/bin/python hello.py

Windows 对应为：

.\.venv\Scripts\python.exe hello.py

这也是排查激活脚本问题的好办法：若显式路径能运行，说明环境本身已创建，问题只在当前 shell 的激活步骤。

退出与重建

退出环境在各平台都可以输入：

deactivate

.venv 里会记录指向解释器的路径，因此它不适合压缩后发给别人，也不应在项目移动后继续硬用。更常见的协作方式是保留依赖清单，让每个人在自己的电脑上重建环境。

用 pip 时始终盯住解释器

pip 是安装和管理 Python 第三方包的工具。最常见的环境事故不是它完全不能用，而是“安装时用了一个 pip，运行时用了另一个 Python”。所以我们把命令写得更明确：

python -m pip --version

在已激活的 .venv 中，Windows、macOS 和 Linux 都可以使用这条命令。输出会同时告诉你 pip 的版本、所在路径以及对应的 Python。路径里出现当前项目的 .venv，才说明后续安装会落到正确地方。

用 python -m pip 明确让当前解释器运行对应的 pip；检查路径一致，才能避免包装进一个环境、代码却由另一个环境运行。

做一次可逆的安装练习

这里以 rich 这个第三方包名演示命令形式。课程后面不依赖它，练习结束可以卸载：

python -m pip install rich
python -m pip show rich
python -c "import rich; print('导入成功')"
python -m pip uninstall rich

安装命令从包索引取得适合当前 Python 和系统的发行文件；show 显示安装位置；第三条让当前 Python 实际导入；最后一条卸载。卸载时会询问确认，输入 y 后回车。

如果网络暂时不可用，不必为了完成第一章强行安装。只要 python -m pip --version 能显示位于 .venv 的 pip，基础环境已经就绪。

包名和导入名不一定相同

pip install 后面的项目名来自包索引，import 后面的模块名来自 Python 代码接口。很多包两者相同，但这不是保证。看到 ModuleNotFoundError 时，既要检查是否装到了正确环境，也要查清这个包实际提供什么导入名，不能把安装命令机械复制到 import 后面。

先别养成全局安装习惯

没有激活虚拟环境时直接安装，包可能进入用户目录或全局目录；有些系统会拒绝并提示环境由外部管理。第一种情况容易日后冲突，第二种其实是在保护系统。回到项目目录、创建并激活 .venv，通常才是学习项目的正确动作。

不要把 --break-system-packages 当作“解决报错”的万能参数。这个名字已经直白说明它会越过系统保护。我们没有必要用一个项目依赖去冒破坏系统 Python 的风险。

常见环境错误怎么顺着线索查

报错时最没帮助的做法，是只截最后一行，或者立刻重装所有工具。环境错误通常会暴露命令、路径和异常类型。按固定顺序检查，很快就能把范围缩小。

提示找不到 python、python3 或 py

这表示 shell 没找到对应命令，不表示你的脚本有语法错误。

先试当前系统推荐的其他入口：Windows 检查 py 和 python，macOS/Linux 检查 python3。再用查找命令确认：

Get-Command python
Get-Command py

command -v python3

若刚完成安装，新开终端再试。仍然找不到时，回到安装来源检查安装管理器、应用执行别名或 PATH，不要先修改代码。

提示 can't open file 或“没有那个文件”

解释器已经启动，但它在当前目录找不到你给出的脚本。检查三件事：

pwd
ls

Windows 使用：

Get-Location
Get-ChildItem

确认当前位置、文件是否列出、文件名大小写和扩展名是否一致。macOS/Linux 通常区分大小写，Hello.py 与 hello.py 可能是两个名字。

提示 ModuleNotFoundError

先打印解释器位置：

python -c "import sys; print(sys.executable)"
python -m pip --version

若一个路径在 .venv，另一个不在，说明环境混用了。若两者一致，再用 python -m pip show 包名 查看包是否确实安装。还要检查当前目录有没有与目标模块同名的文件或目录。

提示权限不足或 externally managed

不要立刻加 sudo。确认你是否位于项目目录并激活 .venv。系统 Python 被包管理器维护时，全局拒绝安装是预期行为。把第三方依赖装进项目虚拟环境，就能绕开文件所有权冲突，同时保护系统工具。

编辑器说找不到模块，终端却能运行

这通常是编辑器语言服务选择了另一个解释器。把编辑器解释器切到项目 .venv，然后重载窗口或重启语言服务。不要因为一条静态提示就在多个环境重复安装同一个包。

出现 SyntaxError 时先看输入位置

如果错误中出现你输入的 python --version、pip install 或 cd，而提示符是 >>>，说明把终端命令写进了 REPL。输入 exit() 回到 shell。

如果错误确实来自 .py 文件，从错误箭头附近开始看。少了引号、括号不配对、使用中文全角符号，都会让解析提前失败。错误箭头有时指向“Python 终于确定不对劲”的位置，真正遗漏可能在上一行。

用四条信息描述问题

需要向别人求助时，把下面信息一起提供：

1. 操作系统
2. 实际执行的完整命令
3. python --version 与 sys.executable 的输出
4. 从 Traceback 开头到最后一行的完整错误

“我装过 Python，但运行不了”需要别人猜很多层；“Windows PowerShell 中执行 py hello.py，py --version 是 Python 3.x，错误显示找不到 D:\learn\hello.py”已经能直接检查目录和文件名。

动手验收你的开发环境

准备工作有没有完成，不看安装界面上出现多少个绿色对勾，而看下面几个动作能否由你亲手复现。

任务一：判断命令应该输入在哪里

把下列内容分成“终端命令”和“Python 代码”：

python3 --version
print("你好")
cd python-start
2 ** 8
python -m pip --version

任务二：写一个能证明环境信息的脚本

在 python-start 中创建 environment_check.py，让它显示一句问候、Python 版本的前三段数字和解释器路径。先自己完成，再展开参考写法。

import sys
 
major = sys.version_info.major
minor = sys.version_info.minor
micro = sys.version_info.micro
 
print("Python 环境可以工作")
print(f"版本：{major}.{minor}.{micro}")
print(f"解释器：{sys.executable}")

任务三：故意制造一次可解释的错误

在终端进入一个不包含 hello.py 的目录，再尝试运行它，观察错误里显示的路径。然后回到 python-start 重新运行成功。

最后的检查单

你应该能够完成这些动作：

• 在终端确认 Python 3 版本，并打印 sys.executable；
• 说清终端提示符与 >>> 的区别；
• 在正确目录保存并运行 hello.py；
• 为项目创建 .venv，激活后确认解释器路径；
• 使用 python -m pip --version 检查包安装位置；
• 遇到找不到命令、找不到文件或找不到模块时，先依据路径排查。

如果其中某一项还不稳定，就回到对应小节重新做一次。环境准备不要求你记住所有系统细节，但必须形成一个习惯：每次都确认“当前终端在哪里、正在调用哪个 Python、包安装到哪个环境”。下一次再遇到报错，你就不会把所有问题都归结成“Python 没装好”。

对照预期输出。如果失败，保留完整命令、解释器路径和第一段错误信息；这些信息比“运行不了”更能指向原因。

若问题与第三方包有关，检查 .venv 是否激活，以及 python -m pip --version 是否落在同一个环境。

激活 .venv 后运行：

版本数字会随你的安装变化，解释器路径应指向当前项目的 .venv。这比照抄固定输出更有意义，因为脚本是在报告你自己的真实环境。