Python 环境搭建完整指南：从下载安装到运行第一个程序

SilentSamsara

467人浏览 · 2026-04-26 15:52:00

SilentSamsara · 2026-04-26 15:52:00 发布

文章目录

一、为什么第一步这么重要

在学 Python 的第一天被环境问题卡住，是一件相当普遍的事。安装了 Python，却不知道该点什么；命令行敲下 python 得到"不是内部命令"；好不容易写了几行代码，满屏红色报错直接懵掉。这些状况和编程能力无关——大多数情况下，只是工具没有配置好。

环境搭建这件事，做好了后续学习一马平川，做不好每次写代码都要和报错搏斗。整个过程只需要搞定三件事：安装 Python 解释器、配置 PATH 环境变量、选一款编辑器。

PATH 配置是绊倒人最多的环节，下面先把它的原理讲清楚。

二、PATH 环境变量到底是什么

理解 PATH 是什么，是彻底解决"python 不是内部命令"这个问题的关键。

2.1 命令行的工作方式

在终端输入 python 并回车时，系统并不是在整个硬盘里大海捞针，而是在一份固定名单里按顺序查找。这份名单就是 PATH 环境变量——它本质是一个目录列表，Windows 上每个目录用分号分隔，macOS/Linux 用冒号分隔。

火车站广播找人可以作为类比：工作人员不会挨个房间去敲门，而是按 A 检票口、B 检票口、C 检票口的顺序依次广播。PATH 就是这份检票口名单，系统按顺序找，找到就停下，找不到就报"不是内部命令"。

2.2 Python 安装目录的结构

安装完 Python 后，安装目录下会有一个 python.exe 文件（Windows）。这个文件的完整路径类似：

C:\Users\用户名\AppData\Local\Programs\Python\Python313\python.exe

如果 PATH 中添加了这个目录，系统就能找到 python 命令；如果没有添加，系统在 PATH 的其他目录中找不到这个命令，就会提示"不是内部或外部命令"。

Python 安装目录的典型结构如下：

关键点：只需要将 Python 安装根目录（如 C:\Python313）添加到 PATH，Scripts 子目录会自动被包含进去，因为 PATH 中的每个目录都会自动搜索其下的所有子目录。

2.3 Windows 手动配置 PATH 详细步骤

如果安装时没有勾选 “Add Python to PATH”（这是最常见的漏选），或者系统仍然找不到 python 命令，需要手动配置。步骤如下：

方法一：命令行快速设置（适合所有 Windows 版本）

以管理员权限打开 PowerShell 或命令提示符，执行以下命令：

# 查看当前 PATH 中已有的内容
echo $env:PATH

# 临时添加 Python 到 PATH（仅对当前窗口有效，重启后失效）
$env:PATH += ";C:\Users\你的用户名\AppData\Local\Programs\Python\Python313"

# 永久添加 Python 到 PATH（写入用户环境变量）
setx PATH "$env:PATH;C:\Users\你的用户名\AppData\Local\Programs\Python\Python313"

方法二：图形界面设置（适合手动操作）

按 Win + R，输入 sysdm.cpl，回车
点击"高级"选项卡 → “环境变量”
在"用户变量"中找到 Path，双击编辑
点击"新建"，输入 Python 安装路径（注意不是 Scripts 子目录）
依次点击"确定"保存

常见错误：将完整路径（包括 python.exe 文件名）添加到 PATH。这会导致系统把整个路径当作一个命令去查找，正确做法是只添加目录，让系统在该目录下自动搜索所有可执行文件。

三、Python 下载与安装

3.1 访问官方下载地址

打开浏览器，访问 python.org/downloads/。页面顶部会显示当前最新版本的下载按钮，下载按钮按照不同操作系统分区排列。

版本选择建议：对于初学者，直接下载页面推荐的最新版本即可。截至 2026 年，Python 3.12 和 3.13 均为稳定版本，3.14 尚处于预发布阶段，不建议作为主力开发版本。

3.2 Windows 安装注意事项

Windows 安装程序会显示两个主要选项：默认的 “Install Now” 会自动安装到用户目录，同时推荐勾选 Add Python to PATH；“Customized Installation” 允许自定义安装路径，但 PATH 需要手动勾选。两种方式最终效果一样，唯一的区别在于 PATH 是否需要自己动手配置。

强烈建议：安装第一步就勾选 Add Python to PATH——这个复选框默认关闭，每年都有大量初学者在这里漏掉，之后又要回头手动配置。

安装完成后，打开命令提示符（Win + R → 输入 cmd → 回车），运行：

python --version
pip --version

两条命令都输出了版本号，说明安装和 PATH 配置全部成功。

安装完成后的验证：打开命令提示符（Win + R → 输入 cmd → 回车），依次输入以下命令：

python --version
pip --version

如果两条命令都输出了正确的版本号，说明安装和 PATH 配置均已成功。

3.3 macOS 安装

macOS 系统从 Catalina（10.15）开始默认使用 Zsh 作为 shell。安装方式主要有两种：

方式一：通过官网下载 pkg 安装包

访问 python.org/downloads/，下载 macOS 安装包，运行后按提示安装。安装完成后，在终端中直接输入 python3 --version 验证。

方式二：通过 Homebrew 安装（推荐）

如果系统已安装 Homebrew（macOS 最常用的包管理器），执行：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install python

Homebrew 会自动配置 PATH，无需手动操作。安装完成后验证：

python3 --version
pip3 --version

注意：macOS 系统自带 Python 2.7，但该版本已停止维护。安装 Python 3 后，系统中的 python 命令可能仍指向旧版本。因此 macOS 上通常需要使用 python3 和 pip3 命令来调用新版本。

3.4 Linux 安装

大多数 Linux 发行版已预装 Python，可以先验证：

python3 --version
pip3 --version

如果没有安装或版本过低，使用系统包管理器安装：

# Ubuntu / Debian
sudo apt update && sudo apt install python3 python3-pip

# Fedora
sudo dnf install python3 python3-pip

# Arch Linux
sudo pacman -S python python-pip

安装完成后验证方法同 macOS。

四、开发环境选择：VS Code 与 PyCharm

Python 程序的编写工具有两大类：文本编辑器（适合轻量级编辑）和 IDE（集成开发环境）（适合大型项目开发）。对于初学者，推荐从 VS Code 开始。

4.1 VS Code：免费、轻量、可扩展

VS Code（Visual Studio Code）是微软开源的代码编辑器，安装包体积小（~100MB），启动速度快，插件生态极其丰富。

安装步骤：

访问 code.visualstudio.com，下载对应操作系统的安装包
安装完成后打开 VS Code
按 Ctrl + Shift + X（或点击左侧扩展图标）打开扩展商店
搜索 Python（由 Microsoft 提供），点击安装

安装 Python 扩展后，VS Code 会自动识别系统中的 Python 解释器。如果有多个 Python 版本共存，按 Ctrl + Shift + P，输入 Python: Select Interpreter，可以选择具体使用哪个版本。

4.2 PyCharm：专业、功能强大

PyCharm 是 JetBrains 出品的 Python 专业 IDE，分为免费社区版（Community）和付费专业版（Professional）。对于初学者，社区版已足够使用。

与 VS Code 的对比：

特性	VS Code	PyCharm Community
费用	免费开源	免费开源
体积	~100MB	~400MB
启动速度	快	较慢
Python 专用功能	需安装扩展	内置，无需额外配置
Django/Flask Web 支持	需插件	内置（专业版）
适合场景	轻量编辑、多语言项目	大型 Python 项目

选择建议：初学者用 VS Code 足矣——免费、轻量、不挑语言；当开始做较大的 Python 项目时，PyCharm 的专业调试工具和代码分析功能会体现出明显优势。

五、pip 包管理器与国内换源

pip 是 Python 的官方包管理器，用于安装和管理第三方库。安装 Python 时 pip 会一并安装，可以通过 pip --version 验证。

5.1 pip 的基本用法

# 安装包
pip install requests

# 指定版本安装
pip install numpy==1.24.0

# 升级包
pip install --upgrade numpy

# 卸载包
pip uninstall numpy

# 查看已安装的包列表
pip list

# 导出依赖列表
pip freeze > requirements.txt

5.2 国内 pip 换源：解决下载速度问题

pip 默认从 PyPI（Python Package Index）下载包，服务器位于国外，国内开发者经常会遇到下载速度极慢甚至超时的问题。解决方案是将 pip 的下载源切换为国内镜像站。

临时换源：在安装命令后加 -i 参数

pip install pandas -i https://pypi.tuna.tsinghua.edu.cn/simple

永久换源：创建配置文件，一劳永逸

# Windows PowerShell
# 在用户目录下创建 pip 配置文件
New-Item -ItemType File -Path "$env:USERPROFILE\pip\pip.ini"

# 写入配置内容（使用阿里云镜像）
@"
[global]
timeout = 6000
index-url = https://mirrors.aliyun.com/pypi/simple/
[install]
trusted-host = mirrors.aliyun.com
"@ | Out-File -Encoding utf8 "$env:USERPROFILE\pip\pip.ini"

# macOS / Linux
mkdir -p ~/.pip
nano ~/.pip/pip.conf
# 写入以下内容

[global]
timeout = 6000
index-url = https://mirrors.aliyun.com/pypi/simple/
[install]
trusted-host = mirrors.aliyun.com

常用国内镜像源：

镜像源	地址	所属
清华大学	https://pypi.tuna.tsinghua.edu.cn/simple	学术机构
阿里云	https://mirrors.aliyun.com/pypi/simple	阿里云
腾讯云	https://mirrors.cloud.tencent.com/pypi/simple	腾讯云
华为云	https://repo.huaweicloud.com/repository/pypi/simple	华为云

为什么选择阿里云？ 各镜像站延迟和稳定性有所差异，在实际使用中阿里云镜像在大多数地区表现最为稳定。如发现某个镜像速度不佳，可尝试更换。

六、运行 Python 的三种方式

Python 代码有三种运行方式，适用于不同的场景：

6.1 交互式解释器（REPL）

在命令行直接输入 python（Windows）或 python3（macOS/Linux），进入 Python 交互式环境：

>>> print("Hello, World!")
Hello, World!
>>> 2 + 3
5
>>> name = "Alice"
>>> f"Hello, {name}"
'Hello, Alice'

这种方式的优点是即输即执行，适合快速验证某个语法、测试某个函数、查看某个变量的值。初学者可以用它来边学边试。

退出交互式解释器，输入 exit() 或按 Ctrl + D（macOS/Linux）或 Ctrl + Z + 回车（Windows）。

6.2 IPython：增强版交互式解释器

pip 默认的交互式解释器功能较为基础。安装 IPython 后可以得到语法高亮、自动补全、命令历史等增强功能：

pip install ipython
ipython

在 IPython 环境中，输入 ? 可查看帮助，输入 %timeit 可以测量代码执行时间：

In [1]: import numpy as np
In [2]: %timeit np.sum(np.arange(10000))
21.9 µs ± 1.54 µs per loop

6.3 运行脚本文件

将代码保存为 .py 文件，通过命令行执行：

python hello.py

这是最常用的运行方式。VS Code 中，打开一个 .py 文件，按 F5 可启动调试模式，按 Ctrl + F5 可直接运行而不进入调试状态。

七、第一个程序与常见报错解读

环境搭建完成后，运行第一个 Python 程序。这里有意设置一个包含常见错误的版本，通过解读报错信息来掌握**“读懂 Python 报错”**这项核心技能。

7.1 准备代码文件

创建名为 hello.py 的文件，内容如下：

# hello.py
print("Hello, Python!")

# ===== 以下是故意设置的错误代码 =====

# 错误1: 变量名拼写错误
message = "欢迎开始 Python 编程"
print(Massage)  # ← 注意这里写成了 Massage

# 错误2: 缺少冒号
x = 10
if x > 5
    print("x 大于 5")

# 错误3: 缩进不一致
y = 20
if y > 10:
print("y 大于 10")  # ← 这行缺少缩进

# 错误4: 引号不匹配
print('Python 是"胶水语言')

运行命令：

python hello.py

7.2 报错信息逐行解读

Python 的报错信息是出了名的友好——它不仅告诉"哪里错了"，还告诉"为什么可能错了"。拿到报错信息后，按以下顺序逐段阅读：

第一次运行结果——NameError: name 'Massage' is not defined：

Traceback (most recent call last):
  File "hello.py", line 7, in <module>
    print(Massage)
NameError: name 'Massage' is not defined

解读步骤：

NameError：名字未定义——Python 在当前作用域中找不到名为 Massage 的变量
print(Massage)：具体出错的位置是第 7 行的 print 函数调用
修复方法：将 Massage 改为 message（第 5 行定义的变量名）

第二次修复后运行结果——SyntaxError: expected ':'：

  File "hello.py", line 10
    if x > 5
           ^
SyntaxError: expected ':'

解读步骤：

SyntaxError：语法错误——Python 在解析代码时就发现了结构不符合语法规则
expected ':'：Python 明确指出这里需要一个冒号 :，但没找到
箭头 ^ 指向位置：箭头指在哪里，就在哪个位置缺少了冒号
修复方法：在 if x > 5 末尾加上冒号

第三次修复后运行结果——IndentationError: expected an indented block：

  File "hello.py", line 14
print("y 大于 10")
IndentationError: expected an indented block

解读步骤：

IndentationError：缩进错误——Python 用缩进来定义代码块（函数体、if 语句体等），这里缩进缺失了
修复方法：在 print("y 大于 10") 前添加 4 个空格（标准的 Python 缩进）

第四次修复后运行结果——SyntaxError: EOL while scanning string literal：

  File "hello.py", line 18
    print('Python 是"胶水语言')
                                ^
SyntaxError: EOL while scanning string literal

解读步骤：

EOL while scanning string literal：字面意思是"在扫描字符串字面量时遇到 EOL（End Of Line，行尾）"——字符串没有正常关闭
箭头指向的位置：箭头在行末，说明 Python 在行末还没找到右引号
修复方法：将开头的单引号改为双引号，或将内部的中文双引号改为单引号：print('Python 是"胶水语言') 或 print("Python 是'胶水语言")

7.3 初学者三大天敌快速定位

错误类型	触发场景	典型报错	修复关键
SyntaxError	语法结构不符合 Python 规则缺冒号、引号不匹配、括号不闭合	`expected ':'` / `EOL while scanning...`	看报错箭头 `^` 指到哪里，那里就是缺失处
NameError	使用了一个没有定义过的变量名或函数名	`name 'xxx' is not defined`	确认变量名拼写是否正确，或是否在引入了相关模块
IndentationError	if/for/函数定义后的代码块缩进不一致	`expected an indented block`	检查缩进是否统一使用空格，混合使用 Tab 和空格是常见诱因

小技巧：VS Code 安装 Python 扩展后，会在输入过程中实时标红有语法问题的代码行，不需要运行程序就能提前发现大部分 SyntaxError。

7.4 修正后的完整代码

将上述所有错误修正后，完整可运行的版本如下：

# hello.py
print("Hello, Python!")

message = "欢迎开始 Python 编程"
print(message)  # ← 修正: Massage → message

x = 10
if x > 5:  # ← 修正: 末尾添加冒号
    print("x 大于 5")

y = 20
if y > 10:
    print("y 大于 10")  # ← 修正: 添加 4 空格缩进

print("Python 是'胶水语言")  # ← 修正: 统一引号类型

运行结果：

Hello, Python!
欢迎开始 Python 编程
x 大于 5
y 大于 10
Python 是'胶水语言'

八、完整环境验证清单

搭建完成后，对照以下清单逐项验证，确保环境完全就绪：

九、环境问题排查速查表

问题现象	根本原因	解决方案
`'python' 不是内部或外部命令`	PATH 中未包含 Python 安装目录	参考第二节的 PATH 配置步骤
`python` 和 `python3` 指向不同版本	系统预装了旧版 Python	使用 `python3` 调用新版，macOS/Linux 建议配置别名
pip 安装包时报错 `ReadTimeout`	默认源下载速度过慢	切换国内镜像源（见第五节）
pip 提示 `Permission denied`	当前用户无写入权限	使用 `pip install --user xxx` 或以管理员运行
VS Code 无法找到 Python 解释器	扩展未安装或 PATH 配置问题	按 `Ctrl + Shift + P`，输入 `Python: Select Interpreter` 手动指定
安装成功但 VS Code 显示"未安装 Python"	VS Code 使用的是系统 PATH，与终端不同	在 VS Code 终端中执行 `python --version` 确认，在 VS Code 命令面板中选择正确的解释器