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

文章目录

- 一、为什么第一步这么重要
- [二、PATH 环境变量到底是什么](#二、PATH 环境变量到底是什么)
- - [2.1 命令行的工作方式](#2.1 命令行的工作方式)
  - [2.2 Python 安装目录的结构](#2.2 Python 安装目录的结构)
  - [2.3 Windows 手动配置 PATH 详细步骤](#2.3 Windows 手动配置 PATH 详细步骤)
- [三、Python 下载与安装](#三、Python 下载与安装)
- - [3.1 访问官方下载地址](#3.1 访问官方下载地址)
  - [3.2 Windows 安装注意事项](#3.2 Windows 安装注意事项)
  - [3.3 macOS 安装](#3.3 macOS 安装)
  - [3.4 Linux 安装](#3.4 Linux 安装)
- [四、开发环境选择：VS Code 与 PyCharm](#四、开发环境选择：VS Code 与 PyCharm)
- - [4.1 VS Code：免费、轻量、可扩展](#4.1 VS Code：免费、轻量、可扩展)
  - [4.2 PyCharm：专业、功能强大](#4.2 PyCharm：专业、功能强大)
- [五、pip 包管理器与国内换源](#五、pip 包管理器与国内换源)
- - [5.1 pip 的基本用法](#5.1 pip 的基本用法)
  - [5.2 国内 pip 换源：解决下载速度问题](#5.2 国内 pip 换源：解决下载速度问题)
- [六、运行 Python 的三种方式](#六、运行 Python 的三种方式)
- - [6.1 交互式解释器（REPL）](#6.1 交互式解释器（REPL）)
  - [6.2 IPython：增强版交互式解释器](#6.2 IPython：增强版交互式解释器)
  - [6.3 运行脚本文件](#6.3 运行脚本文件)
- 七、第一个程序与常见报错解读
- - [7.1 准备代码文件](#7.1 准备代码文件)
  - [7.2 报错信息逐行解读](#7.2 报错信息逐行解读)
  - [7.3 初学者三大天敌快速定位](#7.3 初学者三大天敌快速定位)
  - [7.4 修正后的完整代码](#7.4 修正后的完整代码)
- 八、完整环境验证清单
- 九、环境问题排查速查表
- 写在最后

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

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

环境搭建这件事，做好了后续学习一马平川，做不好每次写代码都要和报错搏斗。整个过程只需要搞定三件事：安装 Python 解释器 、配置 PATH 环境变量 、选一款编辑器。
Windows
macOS
Linux
是
否
是
否
开始
下载 Python 安装包
操作系统
运行安装程序

勾选 Add Python to PATH
下载 pkg 安装包

或使用 Homebrew
系统包管理器安装

或从源码编译
安装验证

python --version
验证成功?
安装编辑器
检查 PATH 配置
PATH 问题?
手动配置 PATH
重新安装 Python
安装 VS Code

配置 Python 扩展
安装 pip 换源

解决下载速度
运行第一个程序
搭建完成

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安装目录
python.exe

Python 解释器主程序
Scripts/

pip.exe 在这里
Lib/

标准库文件
pythonw.exe

无窗口模式
PATH 中只需添加

安装根目录即可

Scripts 子目录自动包含在内

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

2.3 Windows 手动配置 PATH 详细步骤

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

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

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

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------这个复选框默认关闭，每年都有大量初学者在这里漏掉，之后又要回头手动配置。
输出版本号
找不到命令
运行 Python 安装程序
安装选项页面
Install Now

推荐首次安装选这个
Customized Installation

有特殊需求时使用
同时勾选

Add Python to PATH
手动勾选

Add Python to PATH
安装完成
python --version 验证
成功 ✓
手动配置 PATH

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

powershell 复制代码

python --version
pip --version

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

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

powershell 复制代码

python --version
pip --version

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

3.3 macOS 安装

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

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

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

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

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

bash 复制代码

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

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

bash 复制代码

python3 --version
pip3 --version

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

3.4 Linux 安装

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

bash 复制代码

python3 --version
pip3 --version

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

bash 复制代码

# 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 提供），点击安装

VS Code 主界面
左侧Extensions图标
搜索框输入 Python
找到 Microsoft Python 扩展
点击 Install
安装完成后

左下角显示 Python 版本
创建 .py 文件即可使用

智能提示/代码补全/调试

安装 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 的基本用法

bash 复制代码

# 安装包
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 参数

bash 复制代码

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

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

bash 复制代码

# 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"

bash 复制代码

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

ini 复制代码

[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 交互式环境：

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 后可以得到语法高亮、自动补全、命令历史等增强功能：

bash 复制代码

pip install ipython
ipython

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

python 复制代码

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 文件，通过命令行执行：

bash 复制代码

python hello.py

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

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

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

7.1 准备代码文件

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

python 复制代码

# 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 是"胶水语言')

运行命令：

bash 复制代码

python hello.py

7.2 报错信息逐行解读

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

确定错误类型
NameError / SyntaxError / IndentationError
向上看 File 行

确定出错文件和行号
再向上看代码片段

箭头 ^ 指向具体出错位置
结合错误类型

推断修复方案

第一次运行结果 ------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 修正后的完整代码

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

python 复制代码

# 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 解释器
pip 包管理器
编辑器配置
pip 换源
python --version

输出版本号
pip --version

输出版本号
VS Code 安装 Python 扩展

打开 .py 文件有语法高亮
pip install requests -i https://mirrors.aliyun.com/pypi/simple/

下载成功无报错
全部通过

环境搭建完成
重新安装 Python

检查 PATH 配置
重新安装 VS Code

检查 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 命令面板中选择正确的解释器

写在最后

环境搭建这件事，做起来确实没什么成就感------它不涉及任何编程逻辑，不像写出一个排序算法或者调通一个 API 那样有成就感。但它决定了后续所有代码能不能正常跑起来。把这一步彻底做好，后续的学习才不会时不时被环境报错打断。

当命令行输出了 python --version 的版本号，当 VS Code 的 .py 文件出现了彩色语法高亮，当 print("Hello, World!") 输出了意料之中的内容------这三件事同时发生时，就说明环境已经就绪，编程学习可以正式开始了。

如果这篇文章有帮助，欢迎点赞、关注。后续会持续更新 Python 基础系列文章，涵盖语法、数据结构、文件操作、面向对象等核心内容。搭建过程中遇到任何问题，评论区见。