Python Environments

PandaOS detects Python virtual environments in your projects and can automatically activate them for every command PandaOS runs.

Overview

Python projects often use virtual environments (venv, conda, poetry) to isolate dependencies. When PandaOS runs Bash commands in your project, it needs the correct environment activated, otherwise commands like pip install or python script.py may use the wrong Python version or miss project dependencies.

PandaOS solves this by:

1. Auto-detecting virtual environments when you add a project
2. Letting you select from detected environments or enter a custom command
3. Optionally enforcing activation on every Bash command PandaOS runs

Supported Environments

PandaOS checks for environments in the order listed above. If multiple environments exist (e.g., both .venv and a conda env), all are shown in the dropdown so you can pick the right one.

Conda Note

Conda requires a shell hook initialization before conda activate works in non-interactive shells. PandaOS handles this automatically by prepending eval "$(conda shell.bash hook)" to the activation command.

Configuring Python Environments

The Python environment is a per-project setting.

1. Open the project's settings page (the gear on the project overview)
2. Scroll to the Python Environment section
3. Pick a detected environment, or enter a custom activation command

Environment Selector

If PandaOS detected any virtual environments in your project, you'll see a dropdown with:

• None, no environment selected
• Detected environments, each detected env with its label (e.g., .venv, conda: myenv, poetry)
• Custom command..., enter any activation command manually

Select an environment from the dropdown and its activation command is saved automatically.

If no environments are detected, a text input is shown instead where you can type any activation command.

Re-detect Button

Click the refresh icon next to the dropdown to re-scan your project for virtual environments. This is useful after you create a new venv or add an environment.yml.

Custom Commands

Select "Custom command..." from the dropdown to enter any shell command. This is useful for:

• Environments in non-standard locations
• Custom activation scripts
• Nix shells, direnv, or other environment managers

Enforcing Activation

Toggle "Enforce on every Bash command" to automatically prepend the activation command to every Bash command PandaOS runs.

When enabled:

• PandaOS does not need to manually activate the environment, PandaOS does it transparently
• A rule file is created at .pandaos/rules/python-env.md that tells PandaOS the environment is auto-activated
• Commands containing deactivate are skipped (so PandaOS can still deactivate if needed)
• Commands starting with # no-env are skipped, useful for system-level commands

Opting Out Per Command

When enforcement is active, PandaOS can skip activation for individual commands by prefixing them with # no-env:

# no-env
brew install something

This runs the command without the virtual environment.

How It Works

When enforcement is enabled, PandaOS intercepts every Bash tool call and prepends the activation command:

source .venv/bin/activate && <original command>

This happens at the SDK level before the command reaches the shell, so it's transparent to both you and PandaOS. The activation runs in the same shell as the command, ensuring the correct Python and packages are available.

Project Detection

When you add a new project, PandaOS automatically scans for Python environments and stores the first detected command. You can change or disable it at any time in project settings.

Python projects are also detected in the framework detection step, if PandaOS finds pyproject.toml, requirements.txt, setup.py, or dbt_project.yml, the project is identified as a Python project (or dbt project).