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 step is mandatory—without it, your analysis code will fail with scanpy not found.

4.1 The Simplest Approach: omicos env setup

omicos ships with a built-in environment-management command that creates the analysis environment in one shot (under the hood it uses uv to manage the virtual environment):

omicos env setup

This creates a .venv in the default location ~/.omicos/env and installs all the dependencies—scanpy, omicverse, and so on (about 1 GB; the first run is slow). The command is idempotent—running it again won't reinstall an environment that's already in place.

Common options:

Once it's installed, run doctor for a self-check:

omicos env doctor

It reports the kernel interpreter it currently resolves to, whether the key dependencies are in place, the managed environment's location, and the package manager—for example:

kernel python : /path/to/omicos-env/.venv/bin/python3
omicverse     : present ✓
managed env   : /Users/you/.omicos/env
uv            : uv

omicverse : present ✓ means the analysis environment is ready. If it shows as missing, the Python that the interpreter resolves to doesn't have omicverse installed; check that OMICOS_KERNEL_PYTHON / OMICOS_ENV_DIR point to the right environment.

4.2 Specifying the Environment Location: OMICOS_ENV_DIR

The default environment lives in ~/.omicos/env. If you'd rather put it somewhere else (a data disk, a shared directory, etc.), use OMICOS_ENV_DIR to specify it:

# Add to ~/.zshrc or ~/.bashrc to make it permanent
export OMICOS_ENV_DIR=$HOME/my-omicos-env

omicos will look for .venv/bin/python3 under that directory and use it as the kernel interpreter.

4.3 Reusing an Existing conda / venv Environment

If you already have an environment with scanpy/omicverse installed, there's no need to create another one. When omicos resolves the Python interpreter, it tries the following priority chain in order and uses the first match:

OMICOS_KERNEL_PYTHON          # ① Explicit absolute path to the interpreter, highest priority
  └─ .kernel_choice           # ② A previously persisted choice
      └─ OMICOS_ENV_DIR/.venv # ③ omicos's own environment
          └─ PYTHON           # ④ The PYTHON environment variable
              └─ CONDA_PREFIX # ⑤ The currently activated conda environment
                  └─ VIRTUAL_ENV   # ⑥ The currently activated venv
                      └─ python3   # ⑦ System python3 (fallback)

The most direct approach is to pin the interpreter with OMICOS_KERNEL_PYTHON:

export OMICOS_KERNEL_PYTHON=/path/to/your/conda/envs/omicverse/bin/python

Note: The interpreter is detected 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.4 Non-Interactive / Automated Deployment: OMICOS_ENV_AUTO

In CI, Docker, or batch scripts, you don't want omicos to stall on the "Install the environment?" interactive prompt. Set:

export OMICOS_ENV_AUTO=1

On its first launch, omicos will automatically run uv sync to bootstrap the environment instead of asking (this triggers about a 1.5 GB download).

4.5 Remote Kernel: Skipping the Local Environment

If the kernel isn't on this machine but instead runs on a remote HTTP service, you can have omicos connect to it directly and skip the local Python environment bootstrap:

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

Once this is set, omicos no longer tries to create or detect a local Python environment, and all code execution is forwarded to that remote kernel. This is handy in a "thin client + heavy-compute server" architecture.

Summary

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