安装学习环境¶
如果使用在线 IDE，无需在本机执行下面的安装步骤；请先看创建 IDE 环境。本机 Notebook 的扩展安装见本地 Jupyter。
这些课程使用 Python 3.11。SDK 声明支持 Python 3.9–3.13，课程检查则使用 Python 3.11 和文档依赖锁。先选择一个空的工作目录，避免克隆时与已有仓库冲突。
Python 3.11 的安装、四个入门示例和第一课双语报告已在 macOS、Ubuntu、Windows 的自动检查环境中运行通过。检查记录保存了各系统的实际依赖版本；课程推荐先使用这一组合。
学习站上的命令会检出与当前页面相同的源码提交。如果你正在 GitHub 中阅读 Markdown 源文件，先克隆仓库，再选择对应的源码版本进行安装。
克隆仓库、打开源码链接和检查记录都需要仓库访问权限。如果 GitHub 显示“Repository not found”或要求登录，先联系课程维护者，确认当前账号有权限，再继续安装。
git clone https://github.com/CASColdAtom/CASCAQit.git
cd CASCAQit
git checkout 8b227bff1cbfcd7af44525a6f33137f906f6ecc5
创建虚拟环境¶
macOS 或 Linux：
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
Windows PowerShell：
py -3.11 -m venv .venv
.venv\Scripts\python.exe -m pip install -e .
Windows 后续命令中的 python 使用 .venv\Scripts\python.exe 即可，不必先激活环境。安装会包含 NumPy、SciPy 和 Bokeh，学习课程不需要额外安装开发工具或可视化包。
确认环境可用¶
python -c "import sys, cascaqit; print(sys.executable); print(cascaqit.__version__)"
python examples/learning/digital_first_run.py
python examples/learning/analog_first_run.py
解释器路径应指向刚创建的虚拟环境。SDK 版本应与仓库 pyproject.toml 中的版本一致；打包工具可能把 1.0.8a 这样的写法规范化为 1.0.8a0。两个脚本都应正常退出。hardware_execution: False 和 cloud_execution: False 表示本地执行，不是安装失败。
如果 Python 找不到 cascaqit，先检查解释器路径，再使用 python -m pip，确保安装和运行使用同一个解释器。如果找不到示例文件，检查终端是否位于仓库根目录。其他问题见排查问题。
继续之前，关闭当前终端，重新打开一个终端，用这个虚拟环境的解释器再做一次版本检查。这能确认你会重新进入学习环境，而不是偶然用到了全局安装。