---
title: "Venvs"
description: "Isolated Python environments that let components use library versions the platform does not ship"
source_url: https://ai-ops.com/docs/components/venvs
---

# 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.

> [!CAUTION] Uploaded code runs with full privileges
> Only upload wheels from sources you trust. Code installed into a venv runs with full platform privileges on the Koios server.

---

## Venv List

The venv list page shows:

| Column | Description |
|--------|-------------|
| **Status** | Build state, or the state of the worker process running it |
| **Name** | Venv name |
| **Description** | Optional description |
| **Wheels** | Number of wheels installed |
| **Environments** | Number of component environments attached |
| **Worker Memory** | Memory used by the worker process, when one is running |
| **Updated** | Last change |

Click a row to open the venv detail page.

### Status Values

| Status | Meaning |
|--------|---------|
| **Pending** | Queued for building |
| **Building** | Being built now |
| **Build failed** | The build did not finish. Open the **Build** tab for the log |
| **Running** | A worker process is executing attached environments |
| **Worker failed** | The worker stopped unexpectedly. It restarts automatically |
| **Not in use** | Built and ready, but no enabled environment is attached |

---

## 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.

> [!WARNING] Upload every dependency
> Koios installs exactly the wheels you upload and does not download anything else. Upload the package **and** every package it depends on. A missing dependency surfaces as a failed component environment rather than a failed build.

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:

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

Or capture the environment you are working in:

```bash
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

| Symptom | Cause | Fix |
|---------|-------|-----|
| Build failed with a "No solution found" or missing-file error | A dependency was not uploaded | Upload the missing wheels, or import a bundle built with `export-venv` |
| Upload rejected for platform tags | The wheel targets macOS or Windows | Obtain the `manylinux` build of the package |
| Upload rejected for Python version | The wheel targets a different Python | Match the version shown on the venv's Overview tab |
| Component fails with an import error | The package is present but one of its dependencies is not | Upload the missing dependency and rebuild |
| Environment stays stopped | Its venv has not finished building, or the build failed | Check the venv's status and build log |