UnifiedQuantum 安装#

本页帮助你快速完成安装，并在安装后立即验证环境是否可用。若你是第一次接触 UnifiedQuantum，建议先完成本页，再继续阅读 快速上手。

推荐安装方式：通过 uv 安装#

uv 是新一代 Python 包管理工具，安装与构建速度远快于 pip。

中国大陆用户推荐配置清华源，可大幅提升下载速度：

# 永久生效（推荐）
uv pip install --python-preference managed --index-url https://pypi.tuna.tsinghua.edu.cn/simple/

从 PyPI 安装#

# 安装 CLI 工具（推荐，全局可用，无需虚拟环境）
uv tool install unified-quantum

# 安装 Python 包（提供 Python API，可与 CLI 安装共存）
uv pip install unified-quantum

从源码构建#

当你需要安装开发版本、启用 C++ 模拟器或直接修改源码时，可使用源码安装。

平台要求#

  • 操作系统：跨平台，支持 Windows、Linux、macOS

  • Python：>= 3.10, < 3.14

  • C++ 编译器：支持 C++17（MSVC / gcc / clang）

  • CMake：>= 3.26

获取源码#

git clone --recurse-submodules https://github.com/IAI-USTC-Quantum/UnifiedQuantum.git
cd UnifiedQuantum

克隆子模块（C++ 模拟器）#

UnifiedQuantum 的 C++ 模拟器作为 Git 子模块存在。首次克隆后必须初始化子模块，否则 C++ 模拟器不会被包含：

git clone --recurse-submodules https://github.com/IAI-USTC-Quantum/UnifiedQuantum.git
cd UnifiedQuantum

如果克隆时忘记加 --recurse-submodules，后续可以补上：

git submodule update --init --recursive

构建并安装#

# 安装 CLI + Python 包（开发模式，源码可编辑，含全部可选依赖，推荐）
uv tool install -e .[all]

# 仅安装 Python 包（开发模式，不含可选依赖）
uv pip install -e . --no-build-isolation

注意： 从源码构建时 C++ 模拟器为必需组件。如果系统 CMake 版本过低（< 3.26），请先运行 pip install cmake --upgrade 后再执行上述命令。

备选安装方式：通过 pip 安装#

pip 不支持 uv tool install 的 CLI 全局安装方式（无需虚拟环境即可全局调用 uniqc 命令）。如无特殊需求，建议优先使用上面的 uv 安装方式。

从 PyPI 安装#

pip install unified-quantum

从源码构建#

git clone --recurse-submodules https://github.com/IAI-USTC-Quantum/UnifiedQuantum.git
cd UnifiedQuantum

# 完整安装
pip install .

# 开发模式
pip install -e . --no-build-isolation

安装验证#

安装完成后，运行以下命令确认安装成功：

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

若能打印出版本号（如 0.200.0），说明安装成功。

构建 C++ 扩展常见问题#

Q：编译时报 CMake could not find...

确保 CMake 已安装并加入 PATH。Windows 上可使用 CMake 官方安装包。

Q：编译时报 fatal error: pybind11/pybind11.h: No such file

确保已执行 git clone --recurse-submodules，pybind11 子模块未初始化会导致此错误。运行 git submodule update --init --recursive 后重新安装。

Q：如何确认 C++ 模拟器已正确安装？

安装后运行 python -c "from uniqc_cpp import *; print('C++ 模拟器正常')"。若无声出输出说明 C++ 扩展未安装成功。

可选依赖#

核心依赖（numpy、scipy、sympy 等）在默认安装中已包含。以下为可选功能的额外依赖：

OriginQ 平台#

uv pip install unified-quantum[originq]
# 或 pip
pip install unified-quantum[originq]

Quafu 平台#

uv pip install unified-quantum[quafu]
# 或 pip
pip install unified-quantum[quafu]

IBM 平台#

uv pip install unified-quantum[qiskit]
# 或 pip
pip install unified-quantum[qiskit]

高级模拟 (QuTiP)#

uv pip install unified-quantum[simulation]
# 或 pip
pip install unified-quantum[simulation]

可视化#

uv pip install unified-quantum[visualization]
# 或 pip
pip install unified-quantum[visualization]

PyTorch 集成#

uv pip install unified-quantum[pytorch]
# 或 pip
pip install unified-quantum[pytorch]

安装所有可选依赖#

uv pip install unified-quantum[all]
# 或 pip
pip install unified-quantum[all]

开发者补充#

如需本地构建文档，可进入 docs/ 目录后安装文档依赖并执行 make html。这一步仅在维护文档时需要，普通安装可跳过。

下一步#