4. Configure the Python Analysis Environment

The omicos binary itself is just the scheduling kernel — the thing that actually runs scanpy / omicverse is a separate Python environment. This chapter walks through setting it up. Skip this step and analysis code will fail at runtime with Python environment unavailable.

4.1 The Simplest Approach: omicos env setup

omicos env setup

Expected output (first install):

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

This creates a .venv under ~/.omicos/env and installs Python 3.11 + omicverse and the rest of the dependencies (about 1.5 GB, slow on the first run). Under the hood it uses uv; if uv isn't on the machine yet, it's installed automatically first.

The command is idempotent — running it again once the environment is ready just confirms it's there:

omicos env setup

Expected output (environment already exists):

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

Common flags:

If auto doesn't pick a good mirror on a mainland China network, pin one directly:

omicos env setup --index aliyun

Expected output:

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 Self-Check: omicos env doctor

omicos env doctor

Expected output:

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)

Reading it line by line:

• kernel python — the interpreter resolved through the priority chain in §4.4 below; this is the actual Python your analysis code runs in.
• omicverse — whether that interpreter has omicverse installed. MISSING ✗ means the resolved Python isn't the one you thought it was.
• managed env — the environment directory omicos manages itself.
• uv — the uv binary found; if none, shows not found (will be installed on setup).
• package index — the package index currently in use.

When the environment is missing, an extra line is appended:

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

4.3 Listing Candidate Environments: omicos env list

This command emits the candidate Python environments found on the machine as JSON, for scripts and the environment picker used by remote connections:

omicos env list

Expected output:

[{"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 Interpreter Resolution Priority

When omicos decides "which Python to use," it tries the following in order and stops at the first match:

.kernel_choice                 # ① A previously persisted choice (<current directory>/.omicos and ~/.omicos)
  └─ OMICOS_KERNEL_PYTHON      # ② Explicitly specified interpreter path
      └─ OMICOS_ENV_DIR/.venv  # ③ The .venv under that directory
          └─ omicos-env/       # ④ omicos-env found by walking up from the binary's directory
              └─ PYTHON        # ⑤ The PYTHON environment variable
                  └─ CONDA_PREFIX   # ⑥ The currently activated conda environment
                      └─ VIRTUAL_ENV # ⑦ The currently activated venv
                          └─ python3 # ⑧ System python3 (fallback)

Note that .kernel_choice ranks ahead of environment variables. If you've picked a Python once on the web app's "Environment" page, or run omicos hpc and chosen "set as default," that choice gets written to .kernel_choice and from then on it overrides OMICOS_KERNEL_PYTHON. If you exported an environment variable and it doesn't seem to take effect, check which interpreter omicos env doctor reports first, then check <current directory>/.omicos/.kernel_choice and ~/.omicos/.kernel_choice.

4.5 Reusing an Existing conda / venv Environment

If you already have an environment with scanpy / omicverse installed, there's no need to create another one. The most direct approach is to pin the interpreter with OMICOS_KERNEL_PYTHON:

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

Expected output:

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)

You can also use OMICOS_ENV_DIR to point at a directory that contains a .venv:

export OMICOS_ENV_DIR=$HOME/my-omicos-env   # $HOME/my-omicos-env/.venv must exist

OMICOS_ENV_DIR does not change where omicos env setup installs to. It only participates in interpreter resolution. omicos env setup always installs to ~/.omicos/env (the managed env line). To relocate that directory entirely, change OMICOS_LOCAL_HOME instead.

The interpreter is resolved only once, at startup. After changing any of the environment variables above, you need to restart omicos serve / omicos cli for the change to take effect.

4.6 Non-Interactive / Automated Deployment: OMICOS_ENV_AUTO

In CI, Docker, or batch scripts, you don't want omicos to stall on an "install the environment?" prompt:

export OMICOS_ENV_AUTO=1

With this set, omicos automatically installs an environment when it finds none available at startup (about a 1.5 GB download), without asking. Conversely, if this variable isn't set and stdin isn't a TTY, omicos gives a clear error instead of hanging:

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 Remote Kernel: Skipping the Local Environment

If the kernel isn't on this machine but running on a remote HTTP service instead:

export OMICOS_KERNEL_BASE_URL=http://kernel-host:5055
# Or pass --kernel-base-url http://kernel-host:5055 at startup

With this set, omicos doesn't prepare a Python environment locally at all (the environment is provided by the remote side), and code execution is forwarded to that remote kernel.

4.8 When the Environment Is Prepared, and When Errors Show Up

omicos serve doesn't delay startup to wait for the environment. It binds the HTTP port first (chat and file operations are available immediately), and the environment is prepared in the background. So you may see either of these two messages:

This is why it's recommended to run omicos env setup first, then serve — don't let your first analysis collide with an environment that's still installing.

Summary

Once the environment is ready, move on to Chapter 5: First Login.