Miniconda 安装与使用

1. venv、Miniconda 与 Anaconda

Miniconda 和 Anaconda 都用 Conda 管理环境，主要差别是预装内容。 Conda 能安装指定版本的 Python，venv 不负责下载另一个 Python。见 发行方案比较 与 venv 文档。

Miniconda 更轻量，不代表默认软件源没有商业使用限制。 defaults 仓库仍适用对应条款，换成镜像也不改变上游授权条件。下文新环境使用社区 conda-forge，其不适用该仓库的付费要求，仍须遵守服务条款与包许可证。见 官方授权说明。

后文只讲 Miniconda，以 Linux Bash 为命令主线。 日常 conda、pip 用法也适用于 macOS，安装器、校验命令和 shell 初始化有所不同。示例使用 Python 3.13、环境名 demo-env；版本与路径因环境而异。

配图说明：配图来自连接本机 macOS Bash 的终端界面，命令均在临时环境中真实执行；版本和路径因环境而异。正文仍以 Linux Bash 为主线。

2. 安装与初始化

2.1 Linux

以下适用于 Linux x86-64。先核对 系统要求；ARM 设备须选择受支持的 aarch64 安装器，不能直接使用下面的文件。

第一步：下载并计算校验值。

1
2
3

curl -o Miniconda3-latest-Linux-x86_64.sh https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
sha256sum Miniconda3-latest-Linux-x86_64.sh
# 结果：当前目录生成安装脚本，并输出 SHA-256 值与文件名。

将结果与 官方列表 中同名文件的 SHA-256 比较。校验值不一致时不要安装。

第二步：校验通过后运行安装器。

1
2

bash Miniconda3-latest-Linux-x86_64.sh
# 结果：进入协议、安装目录和初始化的交互式安装流程。

1. 阅读协议，确认同意后输入 yes。
2. 确认安装目录，默认通常为 ~/miniconda3；已有安装时不要直接覆盖。
3. 询问是否初始化时输入 yes。
4. 关闭并重新打开终端。

第三步：验证安装。

1
2
3

conda --version
# 示例输出：
# conda 25.11.1

latest 会随官方发布变化，不是固定版本。完整步骤见 Linux 安装说明。

2.2 macOS

Apple Silicon（M 系列）：下载 MacOSX-arm64.sh，校验命令改用 shasum -a 256：

1
2
3

curl -o Miniconda3-latest-MacOSX-arm64.sh https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
shasum -a 256 Miniconda3-latest-MacOSX-arm64.sh
# 结果：下载安装脚本，并输出 SHA-256 值；与官方同名文件比较。

校验通过后执行 bash Miniconda3-latest-MacOSX-arm64.sh，其余交互步骤同上。见 macOS 安装说明。

Intel Mac：默认仓库自 2025 年 8 月 15 日起停止构建 osx-64 新包；历史安装器仍可下载，但不是持续更新的最新版。此变化不等于 conda-forge 同时停止支持。见 官方说明。

2.3 Windows

按 官方安装说明 下载并运行 Windows-x86_64.exe：

1. 个人安装通常选 Just Me，确认安装路径。
2. 不勾选 Add to PATH，避免干扰已有 Python。
3. 安装后打开 Anaconda Prompt，运行 conda --version 验证。这是 Miniconda 也会提供的终端入口名称。

2.4 初始化与 base

若 Linux 安装时跳过了初始化，按实际安装路径执行一次，然后重新打开终端：

1
2

~/miniconda3/bin/conda init bash
# 结果：检查并按需修改 Bash 启动配置；重新打开终端后生效。

macOS 默认 Zsh 则将末尾的 bash 换为 zsh。初始化让 shell 支持环境切换，不是创建项目环境。见 conda init 文档。

base 是 Miniconda 自带的基础环境，项目依赖另建环境安装。不想每次打开终端自动进入默认环境，可执行：

1
2

conda config --set auto_activate false
# 结果：保存配置，通常无输出；以后新终端不再自动激活默认环境。

此设置不退出当前环境；退出用 conda deactivate。旧名称 auto_activate_base 目前仍是别名，见 配置说明。

3. 配置镜像

Conda 源与 pip 源是两套地址，不能混用。 各选一个即可；镜像可能有同步延迟，不要叠加所有镜像。

3.1 可复制的镜像地址

Conda：conda-forge 频道地址。下面是静态地址清单，不是执行命令：

1
2
3
4
5
6
7
8

# 清华 TUNA
https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge
# 中科大 USTC
https://mirrors.ustc.edu.cn/anaconda/cloud/conda-forge
# 北外 BFSU
https://mirrors.bfsu.edu.cn/anaconda/cloud/conda-forge
# 南京大学 NJU
https://mirror.nju.edu.cn/anaconda/cloud/conda-forge

pip：PyPI 镜像地址：

1
2
3
4
5
6
7
8

# 清华 TUNA
https://pypi.tuna.tsinghua.edu.cn/simple
# 中科大 USTC
https://mirrors.ustc.edu.cn/pypi/simple
# 北外 BFSU
https://mirrors.bfsu.edu.cn/pypi/web/simple
# 阿里云
https://mirrors.aliyun.com/pypi/simple/

临时使用示例：以下以清华镜像为例。Conda 命令只查询包；pip 命令请在第 4 节创建并激活项目环境后执行：

1
2
3
4
5

conda search requests --override-channels -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge
# 输出：该镜像中的 requests 版本列表；结果随镜像同步状态变化。

pip install rich -i https://pypi.tuna.tsinghua.edu.cn/simple
# 输出：从指定 PyPI 镜像查找并安装 rich；版本与日志因环境而异。

第 4 节创建并激活环境后，需要让当前用户默认使用清华 PyPI 镜像，可以保存用户级配置：

1
2

pip config --user set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 结果：写入用户级 pip 配置，通常显示已保存的配置文件路径和值。

这里的 --user 指配置文件作用域，会影响读取该用户配置的其他环境，不是 pip install --user。用 pip config debug 检查配置来源；用 pip config --user unset global.index-url 删除这项设置。见 pip 配置说明。

维护方说明：清华、中科大、北外、南京大学、阿里云。中科大的部分频道使用动态缓存，可能重定向到其他镜像站。

3.2 设置 Conda 镜像

先查看配置来源：

1
2

conda config --show-sources
# 输出：生效配置文件的路径与内容；结果取决于本机配置。

编辑 ~/.condarc；已有文件先备份，只调整相关项。以下静态配置使用清华 conda-forge，不加入 defaults：

1
2
3
4

channels:
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge
channel_priority: strict
show_channel_urls: true

strict 表示严格频道优先级，show_channel_urls 显示包来源。

保存后查看实际生效的频道：

1
2
3
4

conda config --show channels
# 仅上述频道生效时，示例输出：
# channels:
#   - https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge

若仍有 defaults 等非预期项，回到 --show-sources 检查其他配置文件；列表可能合并。后续命令以完成此配置为前提，详见 Conda 配置说明。

第 3.1 节临时查询中的 -c 添加频道，--override-channels 排除配置中的其他频道。仅加 -c 不等于只用这一来源。

4. 创建和使用环境

创建 demo-env，安装 Python 3.13 与 pip，再激活：

1
2
3

conda create -n demo-env python=3.13 pip
conda activate demo-env
# 结果：确认安装计划后创建环境；激活后提示符通常出现 (demo-env)。

-n 指定环境名，python=3.13 指定版本系列。激活只影响当前终端，不会切换项目目录；代码不要放进环境目录。

检查当前解释器：

1
2
3
4
5
6
7

python --version
python -c "import sys; print(sys.executable)"
pip --version
# Linux 示例输出；版本与路径因环境而异：
# Python 3.13.16
# /home/you/miniconda3/envs/demo-env/bin/python
# pip 26.2.1 from /home/you/miniconda3/envs/demo-env/lib/python3.13/site-packages/pip (python 3.13)

确认环境看解释器路径，不只看终端前缀。 pip --version 显示的位置也应属于 demo-env。下文完成核对后使用常见简写 pip；未激活环境或存在多个 Python 时，python -m pip 可将 pip 明确绑定到当前 python。

以下命令按需使用，不必依次执行：

-p 路径 可代替 -n 名称 按路径指定环境；-y 跳过确认，未核对安装计划时不要添加。

5. 安装与管理包

Conda 管理环境、Python 版本和 Conda 包，pip 安装 PyPI 包。已配置 conda-forge 时，先用 Conda 安装频道中已有的依赖；频道中没有，或项目明确使用 PyPI 和 requirements.txt 时，再用 pip。

5.1 Conda 命令

激活目标环境，安装 requests，再验证版本：

1
2
3
4
5
6

conda activate demo-env
conda install requests
python -c "import requests; print(requests.__version__)"
# 结果：确认计划后安装 requests 及其依赖。
# 版本示例输出：
# 2.34.2

未激活目标环境时，可用 -n demo-env 显式指定环境，例如 conda list -n demo-env。

5.2 pip 命令

当 Conda 频道没有所需包，或项目使用 PyPI 依赖清单时，先激活环境，再用 pip 安装。

说明：

rich 是个很流行的终端美化库，专门用来让命令行输出变好看。简单说，普通的 print() 只能输出纯文本，而 rich 可以输出：

示例展示结：

以下用 rich 演示：

1
2
3

conda activate demo-env
pip install rich
# 结果：在当前环境安装 rich；版本与日志因环境而异。

先 Conda、后 pip；不要用两者反复覆盖同一个包。 在 Conda 环境中执行 pip install 时不要加 --user。rich 仅用于演示 pip，并非只能用 pip 安装；混用后还需调整 Conda 依赖时，优先按清单重建。见 官方混用建议。

6. 导出依赖与重建

导出的是清单，不是安装包文件。 重建时仍需下载依赖；下面两条路线选其一，不要重复灌入同一环境。

> 和 --file 会覆盖同名文件，导出前确认路径。

6.1 pip：requirements.txt

以下用独立的 pip-demo-env 演示纯 pip 路线，不承接第 5 节同时使用 Conda 和 pip 的 demo-env。

创建原环境、安装依赖并导出：

1
2
3
4
5

conda create -n pip-demo-env python=3.13 pip
conda activate pip-demo-env
pip install rich
pip freeze > requirements.txt
# 结果：创建独立环境、安装 rich，并在当前目录写入 requirements.txt。

在目标机器进入清单所在目录，创建新环境并安装：

1
2
3
4
5
6
7

conda create -n pip-demo-env-copy python=3.13 pip
conda activate pip-demo-env-copy
pip install -r requirements.txt
pip check
# 结果：创建副本，按清单安装依赖；日志取决于清单内容。
# 未检测到依赖问题时，最后输出：
# No broken requirements found.

freeze 也可能列出 Conda 安装但 Python 能识别的包、间接依赖和本机路径；不是只导出 pip 安装的包，也不包含 Python 解释器。分享前检查清单。

-r 表示从文件读取依赖，即常见的 pip install -r requirements.txt。文件名可自定；检查通过后仍需运行项目验证。

6.2 Conda：environment.yml

第 5 节的 demo-env 同时包含 Conda 安装的 requests 和 pip 安装的 rich，应使用本节的混合清单。先导出主动安装的 Conda 依赖：

1
2

conda env export -n demo-env --from-history --file environment.yml
# 结果：生成 environment.yml，记录显式请求的 Conda 依赖。

--from-history 减少间接依赖的平台限制，但不是精确锁文件，也不能代替完整的 pip 清单。删除本机 prefix，核对频道并排除不需要的 defaults，补齐 pip 依赖。

将 environment.yml 整理并保存为下面的配置，不是直接沿用原始导出内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

name: demo-env
channels:
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge
  - nodefaults
dependencies:
  - python=3.13
  - pip
  - requests
  - pip:
      - rich

pip: 列出交给 pip 安装的包。nodefaults 只放在 environment.yml，用于排除其他配置频道；不要放进 .condarc。

在该文件所在目录重建，-n 覆盖文件中的环境名，保留原环境：

1
2
3
4
5

conda env create -n demo-env-copy -f environment.yml
conda run -n demo-env-copy python --version
# 结果：创建 demo-env-copy，并安装清单中的 Conda 与 pip 依赖。
# 版本示例输出：
# Python 3.13.16

若需记录完整状态，使用 conda env export -n demo-env --file environment-full.yml。完整导出含具体版本、构建等信息，仍不保证跨平台重建；分享前检查路径、私有源与认证信息。见 环境管理文档。

7. 删除环境与清理缓存

先用 conda env list 核对名称；如果正在副本环境内，先退出，再删除。以下以第 6.2 节的 demo-env-copy 为例：

1
2
3

conda deactivate
conda env remove -n demo-env-copy
# 结果：退出当前环境，确认后删除 demo-env-copy 及其中的包。

环境目录里的文件会一起删除，外部项目目录不受影响；不要删除 base。 同名环境已有其他用途时，不要执行上面的删除命令。

若使用第 6.1 节的 pip 路线，对应的副本环境名是 pip-demo-env-copy。

8. 常见问题

排查导入错误，在实际报错的位置打印 sys.executable；另一个终端激活了环境，不代表编辑器或 Notebook 已经切换。