Venvs

Navigate to Components > Venvs to manage isolated Python environments. A venv holds a set of Python packages that only the component environments attached to it can see.

Use a venv when a component needs a library the platform does not ship, or a version that conflicts with the one it does. Components that need nothing special run on the platform environment and require no venv at all.

How Venvs Work

You upload wheels into a venv. Koios builds the venv from those wheels and runs every attached component environment inside a dedicated worker process.

Packages in a venv take precedence over the platform's, so a venv containing pandas 2.3.1 gives its components that version even though the platform ships a different one. Everything the platform provides that the venv does not override stays available.

Each venv in use costs one worker process. Budget roughly 200 MB of memory per venv, and reuse a venv across environments rather than creating one per environment.

Venv List

The venv list page shows:

Click a row to open the venv detail page.

Status Values

Creating a Venv

1. Click Add Venv on the list page
2. Enter a name and an optional description
3. Click Create Venv

The venv is created empty. Add packages to it next.

Adding Packages

Open the venv and go to the Wheels tab. There are two ways to add packages.

Uploading Wheels

Drag .whl files onto the upload area, or click to browse. You can drop several at once — the whole batch triggers a single rebuild.

Wheels must be built for Linux (manylinux) and match the Python version shown on the venv's Overview tab. Wheels for macOS or Windows are rejected on upload with a message naming the problem.

Importing a Bundle

A .kvenv bundle collects a package and its full dependency tree in one file. Build one on a development machine with the component builder:

koios-component-builder export-venv -r requirements.txt --name my-venv

Or capture the environment you are working in:

koios-component-builder export-venv --from-env --name my-venv

The bundle downloads Linux wheels for each dependency regardless of the machine you build it on, which makes it the practical way to move a large dependency set onto an air-gapped server.

Click Import Bundle on the list page to create a venv from a bundle, or Import bundle on the Wheels tab to add its packages to an existing venv.

Attaching a Venv to an Environment

1. Open a component environment
2. Go to the Configuration tab
3. Choose the venv under Venv
4. Click Save Configuration

Instances in that environment now run inside the venv. Clearing the field detaches the environment, and its instances go back to running on the platform environment.

Attaching an environment to a venv that failed to build is allowed, but its instances will not run until the build succeeds.

Rebuilding

Koios rebuilds a venv automatically whenever its wheels change. To rebuild on demand — after a Koios upgrade, or to retry a failed build — open the venv and choose Rebuild venv from the actions menu.

A rebuild restarts the worker process, so components in attached environments restart with it. Removing a wheel has the same effect.

Deleting a Venv

Deleting is blocked while any environment is attached. Detach every environment first; the error message names the ones still using it.

Uploaded wheels are included in backups, so restoring a backup restores your venvs. The built environments themselves are not backed up — Koios rebuilds them from the stored wheels on the first start after a restore.

Troubleshooting