目标：NTQ 框架是用python构建的，需要您的本机有python3.9或以上版本。

安装前的准备与检查

先看看电脑里是否已经有 Python？

Windows（PowerShell） 

python --version 

pip --version 

macOS / Linux（终端 Terminal） 

python3 --version 

python --version 

pip3 --version 

如果输出版本 ≥ 3.9：一般可以直接跳到创建虚拟环境。 如果版本过低或命令不存在：按对应系统继续安装。 

Windows 安装 Python 3.9+（推荐：官方安装包） 

步骤1：下载&安装

1. 打开 Python 官网下载页 官方下载页：https://www.python.org/downloads/windows/ 
2. 建议下载： Windows installer（64-bit，除非你明确知道自己需要 32-bit） 
3. 运行安装程序（关键：勾选 Add to PATH） 双击下载的安装包（例如：python-3.12.x-amd64.exe），您会看到安装向导。 
4. 等待安装完成 安装完成后点击 Close

请注意两个非常关键的点：

1. ✅ 勾选 Add python.exe to PATH（非常关键） 
2. 点击 Install Now（适合大多数人）

步骤 2：验证安装（Windows） 

打开 PowerShell 或 命令提示符： 

python --version 

pip --version 

您应该能看到相应的python版本和pip包管理系统的版本

macOS 安装 Python 3.9+（推荐：Homebrew） 

macOS 自带的 Python（或系统工具链）可能不是你需要的版本；推荐使用 Homebrew 管理安装与升级。 

步骤 1：安装 Homebrew（如果你还没有） 

打开“终端 Terminal”，执行： 

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

安装完成后，按终端提示将 brew 加入 PATH（不同 Mac 会提示不同命令，照抄即可）。 

图 4（建议截图）：Homebrew 安装过程/完成提示（含“Next steps”） 

步骤 2：使用 brew 安装 Python（3.9+）

brew update 

brew install python 

Homebrew 会安装较新的 Python 3.x（满足 3.9+）。 

步骤 3：验证安装（macOS）

python3 --version 

pip3 --version 

which python3 

常见现象：python 可能不存在或指向别处，macOS 上优先使用 python3 / pip3 是正常的。 

（备选方案）使用 python.org 的 macOS 安装包 

下载页：https://www.python.org/downloads/macos/ 

安装完成后验证： 

python3 --version 

pip3 --version 

Linux 安装 Python 3.9+ （推荐pyenv）

使用 pyenv 安装指定 Python 版本（3.9+） 

pyenv 适合需要 同时管理多个 Python 版本 的场景（例如项目 A 用 3.9，项目 B 用 3.12）。 

1.安装依赖（Ubuntu/Debian 示例）

sudo apt update

sudo apt install -y \
  build-essential curl git \
  libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

2.安装 pyenv 

curl https://pyenv.run | bash 

然后把下面内容加入你的 shell 配置（二选一）： 

• 如果你用 bash：编辑 ~/.bashrc 或 ~/.bash_profile 
• 如果你用 zsh（macOS/Linux 很常见）：编辑 ~/.zshrc 加入： 

export PYENV_ROOT="$HOME/.pyenv" 
export PATH="$PYENV_ROOT/bin:$PATH" 
eval "$(pyenv init -)" 

重启终端后验证： 

pyenv --version 

3）安装 Python 3.9+ 并启用 例如安装 3.12.x（你也可以换成 3.9.x/3.10.x/3.11.x）： 

pyenv install 3.12.3 

pyenv global 3.12.3 

python --version 

pip --version 

安装完成后的验证（所有系统通用） 

请至少验证以下三件事： 

1）Python 版本 

Windows： 

python --version 

macOS/Linux： 

python3 --version 

2）pip 可用 

Windows： 

pip --version 

macOS/Linux： 

pip3 --version 

3）能正常安装包 

python -m pip install --upgrade pip 

python -m pip install requests 

python -c "import requests; print(requests.__version__)" 

说明：使用 python -m pip ... 比直接用 pip ... 更稳（避免 pip 指向错误的 Python）。 

创建虚拟环境 venv（强烈建议） 

在您的系统中，python是全局的。但是您的不同python项目可能依赖不同版本的相同python包，如果不使用隔离环境，会导致一个包在全局存在多个版本或者版本冲突导致无法使用。创建虚拟环境相当于针对不同项目使用不同python环境，这样能有效地区分不同项目的依赖包从而避免多个系统使用不同版本的依赖而污染全局。下边是创建虚拟环境的步骤： 

1）创建 venv 进入你的项目目录后执行： 

Windows（PowerShell）：

python -m venv .venv 

macOS/Linux：

python3 -m venv .venv 

2）激活 venv 

Windows（PowerShell）： 

.venv\Scripts\Activate.ps1 

Windows（CMD）：

.venv\Scripts\activate.bat 

macOS/Linux： 

source .venv/bin/activate 

激活后你会看到命令行前面出现 (.venv) 之类的标识。 

3）在虚拟环境中安装依赖 （只是举例，不用运行）

python -m pip install -U pip 

python -m pip install flask 

4）退出虚拟环境 

deactivate 

常见问题排查 

1）Windows 输入 python 打开了 Microsoft Store 

原因：Windows 有“应用执行别名”劫持 python.exe。 

解决： 打开 设置 Settings → 应用 Apps → 高级应用设置 Advanced app settings → 应用执行别名 App execution aliases 关闭 python.exe 和 python3.exe 的别名 

重新打开终端测试： 

python --version 

2）Windows 提示 “python 不是内部或外部命令” 

原因：通常是安装时没勾选 PATH，或 PATH 未生效。 

解决： 重新运行安装包 → 选择 Modify → 勾选 Add to PATH 或重启终端/电脑后再试 

3）macOS/Linux 找不到 python，但有 python3 这是正常情况。

建议统一用： python3 / pip3 或用 python -m pip ...（更稳）