2. Prerequisites & System Requirements
This chapter helps you confirm your environment before installing. omicOS needs three things: the omicos binary (the program itself), a Python analysis environment (the engine that runs bioinformatics analyses), and an omicOS cloud account.
2.1 Supported Operating Systems & Platforms
omicos ships prebuilt binaries for six platforms:
| Platform | Architecture | Target triple |
|---|---|---|
| Linux | x86_64 | x86_64-unknown-linux-musl |
| Linux | ARM64 | aarch64-unknown-linux-musl |
| macOS | Intel | x86_64-apple-darwin |
| macOS | Apple Silicon | aarch64-apple-darwin |
| Windows | x64 | x86_64-pc-windows-msvc |
| Windows | ARM64 | aarch64-pc-windows-msvc |
About Linux: the Linux builds use musl static linking (rather than glibc), which sidesteps compatibility issues caused by differing libc versions across distributions — the same binary runs on Ubuntu, CentOS, and HPC login nodes alike.
Once installed, confirm which platform build you got with omicos --version:
omicos --version
Output format (use the version and commit reported by your installation):
omicos <version>+<commit>
2.2 Installation Methods
omicos is installed by fetching a prebuilt binary via npm, which only requires Node.js ≥ 16:
| Installation method | What you need | Who it's for |
|---|---|---|
| Install prebuilt package via npm | Node.js ≥ 16 | All users |
npm automatically downloads the binary matching your system from the table above — no compiler toolchain required. See Chapter 3 for details.
2.3 Python Analysis Environment
omicos itself is just a scheduling kernel — the thing that actually runs scanpy / omicverse is a separate Python environment (Python 3.11 + omicverse, about 1.5 GB).
- The recommended approach is to create it in one step with
omicos env setup(which manages the virtual environment under the hood with uv). - You can also point it at an existing conda / venv environment.
See Chapter 4: Configuring the Python Analysis Environment for details.
Check the Environment in the App
Open Environments from the client's sidebar, find the target workspace, and inspect Execution location at the bottom of its card. These native App screenshots show the full interface with the default light theme and Chinese labels. Personal workspace and environment names and paths are masked; the built-in default environment and status labels remain visible. Click an image to view it at full size.
The kernel is marked running and hot/ready, but the selected Python environment is marked unavailable. Kernel status and analysis-environment status are separate. If you see this warning, prepare the environment as described in Chapter 4 before running analyses.
Click the environment name under execution location to expand the environments detected on this machine:
Names and paths depend on your installation; this is not a list to copy. Detection does not guarantee that omicverse and analysis dependencies are installed. Check the Python version and required packages before selecting an environment.
Note: environment problems surface lazily. Without a configured environment,
omicos servestill starts fine and chat still works — it prepares the environment in the background without blocking startup. You'll only seePython environment unavailable: …(orThe Python environment is still being prepared…while it's still installing) once you actually try to run analysis code. So set up the environment ahead of time, rather than discovering the gap mid-analysis.
2.4 omicOS Cloud Account
Agent chat, cross-device viewing, image hosting, and subscription tiers all depend on a cloud account:
- Register at auth.omicos.cn.
- See Chapter 5 for sign-in methods.
2.5 Network Requirements
- omicos needs access to
auth.omicos.cnfor login, process registration, and syncing. - By default it only listens on
127.0.0.1and exposes no public ports; remote access is done through SSH port forwarding — see the remote deployment recipes for details. - If your machine is behind an HTTP proxy, allow-list the loopback address (
export no_proxy=localhost,127.0.0.1). Otherwise the proxy may intercept the kernel's outbound requests and the browser's connection tolocalhost:5055, showing up as "it just won't connect." omicos prints a bilingual warning at startup when it detects this kind of configuration.
Checklist
Before you start installing, confirm:
- [ ] Your OS is one of the six platforms above
- [ ] Node.js ≥ 16 is installed
- [ ] You've registered an account at auth.omicos.cn
- [ ] The machine has internet access (at minimum, it can reach
auth.omicos.cn)
Once these are met, move on to Chapter 3: Installing via npm.

