> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/python-virtual-environments/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Python virtual environments

When Gateway executes a `python-script` service, `ansible-playbook` service, or a `runCode` task, it builds an isolated virtual environment on the runner containing the dependencies that execution requires. This topic explains how Gateway manages those environments and how to configure automatic cleanup.

## How Gateway manages virtual environments

Gateway caches virtual environments so that dependencies are installed once and reused across executions. Each environment is keyed to a specific set of dependencies — when the requirements for a service or task are unchanged, Gateway reuses the existing environment rather than reinstalling. On each execution, Gateway:

1. Checks whether a virtual environment already exists for the required dependency set.
2. If a matching environment exists, reuses it.
3. If no matching environment exists, builds a new one by installing the required dependencies, then caches it for future use.
   Because environments are cached and reused, repeated executions with the same dependency set incur no reinstall overhead.

For `python-script` and `ansible-playbook` services, dependencies are read from a `requirements.txt` file in the service's working directory. `python-script` services also support `pyproject.toml` as an alternative to `requirements.txt`.

For `runCode` tasks, dependencies are specified at design-time in the task's Code Editor dialog.

## Virtual environment pruning

Gateway 5.4+

Without cleanup, cached virtual environments accumulate on disk over time. As of Gateway 5.4, Gateway includes a background pruner that automatically removes environments that have been idle beyond a configurable retention period.

Two configuration parameters control pruner behavior:

| Setting                 | Environment variable                        | Default | Description                                                                                              |
| ----------------------- | ------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `venv_sweep_interval`   | `GATEWAY_APPLICATION_VENV_SWEEP_INTERVAL`   | `24h`   | How often the pruner scans for idle environments. Accepts Go durations (`12h`) or plain days (`1d`).     |
| `venv_retention_period` | `GATEWAY_APPLICATION_VENV_RETENTION_PERIOD` | `30d`   | How long an environment may be idle before removal. Accepts Go durations (`720h`) or plain days (`30d`). |

Both settings are configurable in `gateway.conf` under the `[application]` section or via environment variables. For more information, see [Application variables](./gateway-application-variables).

### Tune the retention period

If you set `venv_retention_period` too low, Gateway may prune an environment between uses and force a full dependency reinstall on the next execution, adding latency to that run.

When tuning the retention period, consider how frequently your services and tasks run. If some run infrequently — for example, monthly maintenance scripts — set the retention period to exceed the longest interval between executions for those services.