`from qiskit import Aer, execute` 报错：ModuleNotFoundError 或 AttributeError

Question

**问题：** 执行 `from qiskit import Aer, execute` 时频繁报错——`ModuleNotFoundError: No module named 'qiskit.aer'` 或 `AttributeError: module 'qiskit' has no attribute 'Aer'`。该问题自 Qiskit 1.0 版本（2024年3月发布）起尤为普遍，根本原因在于 Qiskit 已彻底重构模块架构：`qiskit-aer` 不再随 `qiskit` 主包自动安装，且 `execute()` 函数已被弃用并移至 `qiskit.primitives` 模块。用户若沿用旧教程、未升级依赖或仅运行 `pip install qiskit`（不包含可选子包），便会触发上述错误。此外，虚拟环境隔离、conda/pip 混装、或残留旧版（如 0.45.x）与新版共存，亦会引发符号解析失败。如何在 Qiskit ≥1.0 环境中正确导入仿真器并运行电路？需明确区分安装命令、导入路径与执行接口的变更。

Answer 1

```html

一、现象层：错误表征与典型报错现场

开发者在 Qiskit ≥1.0 环境中执行 from qiskit import Aer, execute 时，高频触发两类核心异常：

• ModuleNotFoundError: No module named 'qiskit.aer' —— 模块未安装或路径解析失败；
• AttributeError: module 'qiskit' has no attribute 'Aer' —— 符号未注入主命名空间，反映架构解耦事实。

这两类错误并非运行时逻辑缺陷，而是 Qiskit 1.0 强制推行的「模块原子化」与「API 显式化」设计原则的直接外显。旧式单包隐式导入范式（如 qiskit.Aer 自动可用）已彻底失效。

二、架构层：Qiskit 1.0 模块拆分全景图

Qiskit 自 1.0 起采用“核心+插件”微内核架构，原 qiskit 单体包被拆分为多个独立可安装组件：

子包名	功能定位	是否默认随 pip install qiskit 安装？
qiskit	仅含顶层入口、基础类型（QuantumCircuit）、工具链（transpile等）	✅ 是
qiskit-aer	高性能量子电路仿真器（CPU/GPU/OpenMP）	❌ 否（需显式安装）
qiskit-primitives	统一执行接口：Sampler/Estimator，替代已移除的 execute()	✅ 是（但 execute 函数本身已删除）

三、依赖层：安装策略与环境治理

必须摒弃 pip install qiskit 的惯性操作。正确安装组合如下：

# ✅ 推荐：安装完整生态（含 Aer + Primitives + IBM Provider）
pip install qiskit[all]

# ✅ 最小可行：仅 Aer 仿真能力（不含云后端）
pip install qiskit qiskit-aer

# ⚠️ 风险操作：conda/pip 混装将导致 import qiskit.aer 解析失败（因 conda-forge 的 qiskit-aer 与 pip 版本 ABI 不兼容）
# 建议全程使用 pip 或全程使用 conda（推荐 conda-forge 频道）

四、代码层：从旧范式到新范式的迁移路径

以下为等效功能的代码演进对比（基于 Qiskit 1.0.3+）：

# ❌ 旧写法（Qiskit <1.0，已失效）
from qiskit import Aer, execute
backend = Aer.get_backend('aer_simulator')
job = execute(circuit, backend)
result = job.result()

# ✅ 新写法（Qiskit ≥1.0）
from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator  # 注意：导入路径变为 qiskit_aer（下划线），非 qiskit.aer
from qiskit.primitives import Sampler  # 替代 execute() 的现代接口

simulator = AerSimulator()
sampler = Sampler(backend=simulator)
job = sampler.run(circuit)  # 返回 PrimitiveJob 对象
result = job.result()  # result.quasi_dists / result.metadata 等结构化输出

五、诊断层：快速验证与故障树分析

当问题复现时，执行以下诊断序列：

1. 检查版本：python -c "import qiskit; print(qiskit.__version__)"; pip show qiskit-aer
2. 验证模块存在：python -c "import qiskit_aer; print(qiskit_aer.__version__)"
3. 确认无残留旧版：pip list | grep qiskit → 若出现 qiskit-terra, qiskit-aer 等 0.x 分离包，说明环境污染，需 pip uninstall qiskit-terra qiskit-aer qiskit-ignis ... 彻底清理

六、工程层：CI/CD 与虚拟环境最佳实践

为规避多环境不一致，建议在 pyproject.toml 中声明精确依赖：

[project.dependencies]
qiskit = "^1.0.3"
qiskit-aer = "^0.14.2"  # 与 qiskit 主版本对齐的 aer 版本号见 https://qiskit.org/documentation/versioning.html
qiskit-primitives = "^0.6.0"

并强制 CI 流水线使用干净虚拟环境：python -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -e .

七、演进层：为什么 Qiskit 1.0 必须如此重构？

根本动因是解决长期技术债：

• 可维护性：原 qiskit 包含 12+ 子模块，每次发布需全量测试，CI 耗时超 4 小时；拆分后各模块可独立发版（如 qiskit-aer 每月迭代，qiskit-ibm-provider 每周更新）；
• 可扩展性：第三方可轻松实现 qiskit-myprovider 并注册为 BackendV2 兼容接口；
• 可部署性：嵌入式设备仅需 qiskit + qiskit-aer（≈15MB），无需拉取 IBM Cloud 依赖（≈85MB）。

八、未来层：向 Qiskit 2.0 过渡的关键信号

当前（2024年Q3）已有预示性变更：

• qiskit.primitives.Sampler 已标记为 @deprecatable，未来将由 qiskit.primitives.backends.SamplerBackend 统一建模；
• QuantumCircuit 的 .measure_all() 行为正向硬件语义收敛（自动插入 classical register）；
• 官方文档已启用「版本切换器」，旧版 API 文档明确标注 [DEPRECATED]。

九、实战层：一个端到端可运行的最小验证脚本

#!/usr/bin/env python3
"""Qiskit 1.0+ 最小可运行验证脚本"""
try:
    from qiskit import QuantumCircuit
    from qiskit_aer import AerSimulator
    from qiskit.primitives import Sampler
except ImportError as e:
    print(f"缺失关键模块：{e}")
    exit(1)

# 构建贝尔态电路
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

# 执行流程（无 execute()！）
sim = AerSimulator()
sampler = Sampler(backend=sim)
job = sampler.run(qc)
result = job.result()

print(f"✅ 采样成功：{result.quasi_dists[0]}")
print(f"⏱️  执行耗时：{result.metadata['time_taken']:.3f}s")

十、决策层：技术选型决策树（Mermaid 流程图）

flowchart TD
    A[遇到 ModuleNotFoundError/Aer AttributeError] --> B{是否已运行 pip install qiskit-aer?}
    B -->|否| C[执行 pip install qiskit-aer]
    B -->|是| D{是否混用 conda/pip?}
    D -->|是| E[完全卸载：conda remove qiskit && pip uninstall qiskit*]
    D -->|否| F{是否残留 qiskit-terra?}
    F -->|是| G[pip uninstall qiskit-terra qiskit-aer qiskit-ignis]
    F -->|否| H[检查 python -c \"import qiskit_aer\"]
    C --> H
    E --> I[conda install -c conda-forge qiskit]
    G --> I
    H -->|成功| J[迁移到 Sampler/AerSimulator 新范式]
    H -->|失败| K[检查 PYTHONPATH / virtualenv 激活状态]

```