4. 配置 Python 分析环境

omicos 二进制只负责调度。真正运行 scanpy / omicverse 的是一个独立 Python 环境。配好它，否则运行分析代码时报 Python environment unavailable。

4.1 最简方式：omicos env setup

omicos env setup

预期输出（首次安装）：

Preparing the OmicOS analysis environment (Python 3.11 + omicverse, ~1.5 GB)
  target: /Users/you/.omicos/env
  probing Python package indexes...
  package index: pypi (https://pypi.org/simple, auto)
  · downloading + installing packages with uv (first run is the slow one)…
  …
  ✓ environment ready: /Users/you/.omicos/env/.venv/bin/python3

它在 ~/.omicos/env 下建一个 .venv，装齐 Python 3.11 + omicverse 等依赖（约 1.5 GB，首次较慢）。底层用 uv。机器上没有 uv 时会先自动装一个。

这个命令是幂等的——环境已就绪时重复运行只会确认一下：

omicos env setup

预期输出（环境已存在）：

✓ environment already present: /Users/you/.omicos/env/.venv/bin/python3

常用参数：

国内网络下 auto 探测不理想时，直接钉死镜像：

omicos env setup --index aliyun

预期输出：

Preparing the OmicOS analysis environment (Python 3.11 + omicverse, ~1.5 GB)
  target: /Users/you/.omicos/env
  package index: aliyun (https://mirrors.aliyun.com/pypi/simple, cli)
  · downloading + installing packages with uv (first run is the slow one)…
  …
  ✓ environment ready: /Users/you/.omicos/env/.venv/bin/python3

4.2 自检：omicos env doctor

omicos env doctor

预期输出：

kernel python : /Users/you/.omicos/env/.venv/bin/python3
omicverse     : present ✓
managed env   : /Users/you/.omicos/env
uv            : /Users/you/.local/bin/uv
package index : pypi (https://pypi.org/simple)

逐行读：

• kernel python —— 按 4.4 的优先级链解析出的解释器，即分析代码实际运行的 Python。
• omicverse —— 那个解释器里有没有 omicverse。显示 MISSING ✗，说明解析到的 Python 不对。
• managed env —— omicos 自己管理的环境目录。
• uv —— 找到的 uv。没有则显示 not found (will be installed on setup)。
• package index —— 当前使用的包索引源。

环境缺失时，最后还会多一行提示：

Run `omicos env setup` to install the bundled environment.

4.3 列出候选环境：omicos env list

这条命令把机器上发现的候选 Python 环境以 JSON 输出。供脚本和远程连接的环境选择器使用：

omicos env list

预期输出：

[{"python":"/Users/you/.omicos/env/.venv/bin/python3","has_omicverse":true},{"python":"/opt/miniforge3/envs/omicverse/bin/python3","has_omicverse":true},{"python":"/opt/miniforge3/bin/python3","has_omicverse":false}]

4.4 解释器解析优先级

omicos 决定「用哪个 Python」时按以下顺序逐项尝试，命中即用：

.kernel_choice                 # ① 之前持久化的选择（<当前目录>/.omicos 与 ~/.omicos）
  └─ OMICOS_KERNEL_PYTHON      # ② 显式指定解释器路径
      └─ OMICOS_ENV_DIR/.venv  # ③ 该目录下的 .venv
          └─ omicos-env/       # ④ 从二进制所在目录逐级向上查找的 omicos-env
              └─ PYTHON        # ⑤ PYTHON 环境变量
                  └─ CONDA_PREFIX   # ⑥ 当前激活的 conda 环境
                      └─ VIRTUAL_ENV # ⑦ 当前激活的 venv
                          └─ python3 # ⑧ 系统 python3（兜底）

4.5 复用已有的 conda / venv 环境

已有装好 scanpy / omicverse 的环境时，不必重建。用 OMICOS_KERNEL_PYTHON 钉死解释器：

export OMICOS_KERNEL_PYTHON=/opt/miniforge3/envs/omicverse/bin/python
omicos env doctor

预期输出：

kernel python : /opt/miniforge3/envs/omicverse/bin/python
omicverse     : present ✓
managed env   : /Users/you/.omicos/env
uv            : /Users/you/.local/bin/uv
package index : pypi (https://pypi.org/simple)

也可以用 OMICOS_ENV_DIR 指向一个包含 .venv 的目录：

export OMICOS_ENV_DIR=$HOME/my-omicos-env   # 需存在 $HOME/my-omicos-env/.venv

OMICOS_ENV_DIR 不改变 omicos env setup 的安装位置。 它只参与解释器解析。omicos env setup 永远装到 ~/.omicos/env（managed env 那一行）。要整体搬走这个目录，改的是 OMICOS_LOCAL_HOME。

解释器只在启动时解析一次。改了上述任何环境变量，需要重启 omicos serve / omicos cli 才生效。

4.6 非交互 / 自动化部署：OMICOS_ENV_AUTO

在 CI、Docker、批处理脚本里，避免 omicos 卡在「是否安装环境？」提示上：

export OMICOS_ENV_AUTO=1

设置后，omicos 启动时发现没有可用环境会自动装（约 1.5 GB 下载），不再询问。既没设这个变量、stdin 又不是终端时，omicos 直接报错，不傻等：

No OmicOS Python environment found and stdin is not a TTY, so I can't prompt.
Run `omicos env setup` once, or set OMICOS_ENV_AUTO=1 to install it non-interactively (~1.5 GB → /Users/you/.omicos/env).

4.7 远程 kernel：跳过本地环境

kernel 不在本机、跑在远程 HTTP 服务上时：

export OMICOS_KERNEL_BASE_URL=http://kernel-host:5055
# 或启动时传 --kernel-base-url http://kernel-host:5055

设置后，omicos 不在本地准备 Python 环境（由远端提供）。代码执行转发到该远程 kernel。

4.8 环境何时准备、何时报错

omicos serve 不会为等环境而推迟启动。它先绑定 HTTP 端口（聊天、文件操作立即可用），环境在后台准备。你可能会遇到两条信息：

所以建议先 omicos env setup，再 serve。避免第一次分析撞上正在安装的环境。

下一步

小结

环境就绪后，进入第 5 章：首次登录。