Python Manager

The Python Manager LOP creates and manages Python virtual environments, installs packages via pip or UV, and controls which venv site-packages are available in TouchDesigner’s sys.path. Environment registrations are stored in a three-tier JSON config system that separates machine-specific paths from portable project settings.

Most users do not need to place this operator. ChatTD includes a built-in Python Manager that handles dependency installation for all LOPs operators automatically. Use the standalone Python Manager only when you need:

• A separate venv with a different Python version than the shared LOPs venv
• An isolated environment for a specific operator or workflow (e.g., a custom ML model with conflicting dependencies)
• Manual control over multiple registered environments across projects

Key Features

• Dual backend support — UV (fast, auto-downloads Python) or pip (standard, uses system Python)
• Three-tier config system — register environments at the user, project folder, or project level with automatic merging and deduplication
• sys.path management — toggle individual venvs into TouchDesigner’s import path with per-environment import controls
• Stale path detection — status field flags environments whose paths no longer exist on disk, useful when moving projects between machines
• Auto-migration — legacy sequence-based environment registrations are automatically migrated to the JSON config system on first load
• Requirements file support — install from or export to requirements.txt
• Cross-platform — works on Windows and macOS

Input/Output

This operator has no wired inputs. It has one output but is primarily configured through its parameter panel and exposes its functionality to other operators via promoted methods.

Three-Tier Config System

Environment registrations are stored across three tiers, merged at load time with higher tiers overriding lower ones when names collide:

Tier	Location	Use Case
User	{AppData}/ChatTD/python_config.json	Machine-specific absolute paths. Persists across all projects on this computer.
Project Folder	{project.folder}/.lops/python_config.json	Portable relative paths. Travels with the project folder, resolves correctly on any machine.
Project	Text DAT inside the operator	Embedded in the .toe file. Travels with the project file itself. Highest priority.

Priority for deduplication: Project > Folder > User. If the same environment name appears in multiple tiers, the highest-priority tier wins.

Choosing a Config Tier

On the Environments page, the Save New Envs To menu controls where newly created or registered environments are stored:

• User Config — best for machine-local venvs that should persist across all projects (e.g., a shared ML environment)
• Project Folder (.lops/) — best for venvs that live inside or near the project folder and should be portable to other machines. Paths inside the project folder are automatically stored as relative paths.
• Project (.toe) — best for venvs that must travel embedded in the .toe file. Useful when distributing a self-contained project.

The read-only Config Path field shows the resolved filesystem path for the active tier (or “(stored in operator DAT)” for the Project tier).

Usage Examples

Creating a New Virtual Environment

1. On the Python Env page, set the Backend to your preferred package manager (UV is recommended for speed)
2. If using UV, choose a Python Version (UV) and optionally set Venv Options (e.g., “Seed” to include pip/setuptools in the venv)
3. Set a Base Folder to the directory where the venv should be created
4. Pulse Create Venv — a venv/ subfolder is created inside your base folder and automatically registered to the active config tier
5. Toggle Add to sys.path on if you want the venv’s packages available for import inside TouchDesigner

No folder set?

If you pulse Create Venv without setting a Base Folder, a folder picker dialog opens automatically.

Installing Packages

1. Select the target environment from the Selected Environment menu, or leave on “Custom / New Venv” to use the Base Folder path
2. Under Install / Manage Packages, type one or more package names in the Package field (space-separated)
3. Pulse Install, Uninstall, or Update as needed
4. To bulk-install, point the Requirements File parameter to a requirements.txt and pulse Install from File

Registering an Existing Venv

If you already have a venv on disk that was created outside of LOPs:

1. On the Python Env page, set Base Folder to the parent directory containing the venv/ folder
2. Pulse Create Venv — the operator detects the existing venv and registers it without recreating it
3. The environment appears on the Environments page and in the Selected Environment menu

Managing Multiple Environments

The Environments page holds a sequence of registered venvs, rebuilt automatically from the merged JSON config on each load. Each entry shows:

• name — a label for the environment
• path — the resolved filesystem path to the venv directory
• import — toggle to add/remove this venv’s site-packages from sys.path (runtime-only, not persisted to the JSON config)
• open — pulse to open a terminal with the venv activated
• Status — read-only field showing the config tier label (e.g., [user], [folder], [project]), an import indicator, and the Python version. Shows STALE if the path no longer exists.

Display-only sequence

The Environments sequence is rebuilt from the JSON config files each time the operator initializes. Editing sequence entries directly (adding/removing rows) does not modify the underlying config. Use the config tier system to add or remove environments persistently.

When a venv is removed from the sequence and On Seq Remove is set to “Auto-remove from sys.path,” its site-packages path is automatically cleaned from sys.path.

Refreshing and Editing Config

• Pulse Refresh Registry to reload environments from all three config tiers and rebuild the sequence display
• Pulse Edit Config File to open the active tier’s JSON file in your system text editor (User or Folder tier). For the Project tier, edit the project_venv_config text DAT directly inside the operator.

Best Practices

• Use UV as the backend for faster venv creation and package installation. UV auto-downloads the requested Python version, so you do not need a standalone Python install.
• Use the Project Folder tier for team projects — relative paths resolve correctly when collaborators clone the project to different locations.
• Use the User tier for large shared environments (e.g., a PyTorch/CUDA venv) that should be available across all your projects without duplication.
• Check the Status column after moving a project to a new machine. Environments marked STALE need their paths updated or the venv recreated locally.

Troubleshooting

• “UV Not Found” — UV is not installed on the system. The operator will prompt you to switch to the pip backend. Alternatively, install UV separately.
• “No compatible Python found” — When using the pip backend, a standalone Python matching TouchDesigner’s version must be installed on the system. UV avoids this requirement by downloading Python automatically.
• Packages not importable after install — Make sure the environment’s import toggle is enabled on the Environments page, or that Add to sys.path is on for the primary environment on the Python Env page.
• STALE environments after moving projects — The venv path no longer exists on this machine. Either recreate the venv locally with the same Base Folder, or update the path in the config JSON via Edit Config File.
• Sequence looks empty after upgrade — On first load after upgrading from a pre-config version, the operator auto-migrates legacy sequence entries to the User config tier. Pulse Refresh Registry if entries do not appear immediately.

Parameters

Python Env

Status (Status) op('python_manager').par.Status Str

Current status message

Default:

"" (Empty String)

Selected Environment (Selectedenv) op('python_manager').par.Selectedenv Menu

Select registered environment or Custom to use Base Folder

Default:

custom

Options:

custom

Base Folder (Basefolder) op('python_manager').par.Basefolder Folder

Root folder for custom virtual environment

Default:

"" (Empty String)

Create Venv (Createvenv) op('python_manager').par.Createvenv Pulse

Create virtual environment in Base Folder

Default:

False

Add to sys.path (Addtosyspath) op('python_manager').par.Addtosyspath Toggle

Add venv site-packages to TouchDesigner sys.path. Syncs with sequence import toggle.

Default:

False

Open Console (Openvenv) op('python_manager').par.Openvenv Pulse

Open terminal with venv activated

Default:

False

Backend (Backend) op('python_manager').par.Backend Menu

Package manager backend. UV auto-downloads Python, pip uses system Python.

Default:

uv

Options:

uv, pip

Python Version (UV) (Pythonversion) op('python_manager').par.Pythonversion StrMenu

Python version for UV venv creation

Default:

"" (Empty String)

Menu Options:

• 3.9 (3.9)
• 3.10 (3.10)
• 3.11 (3.11)
• 3.12 (3.12)
• 3.13 (3.13)

Venv Options (Venvoptions) op('python_manager').par.Venvoptions StrMenu

UV venv creation flags. Isolated is default. Seed adds pip/setuptools. You can type custom UV args.

Default:

"" (Empty String)

Menu Options:

• None (Isolated) (none)
• Seed (pip/setuptools) (--seed)
• System Packages (--system-site-packages)
• Relocatable (--relocatable)
• Seed + Relocatable (--seed --relocatable)

Detected Python (Pythonexe) op('python_manager').par.Pythonexe Str

Auto-detected Python executable path

Default:

"" (Empty String)

Use Custom Python (Custompython) op('python_manager').par.Custompython Toggle

Use a custom Python from the menu below instead of auto-detected

Default:

False

Custom Python (Pythonexemenu) op('python_manager').par.Pythonexemenu StrMenu

Default:

"" (Empty String)

Menu Options:

• Python311 (C:/Users/DotSimulate/AppData/Local/Programs/Python/Python311/python.exe)
• Python311 (C:\Users\DotSimulate\AppData\Local\Programs\Python\Python311\python.exe)
• Python310 (C:\Users\DotSimulate\AppData\Local\Programs\Python\Python310\python.exe)
• python.exe (C:\Users\DotSimulate\AppData\Local\Microsoft\WindowsApps\python.exe)
• python.exe (C:\Users\DotSimulate\AppData\Local\Microsoft\WindowsApps\python.exe)

Refresh Python (Setpython) op('python_manager').par.Setpython Pulse

Re-detect available Python installations

Default:

False

Install / Manage Packages Header

Package (Pippackage) op('python_manager').par.Pippackage Str

Package name(s) to install/uninstall (space-separated)

Default:

"" (Empty String)

Install (Pipinstall) op('python_manager').par.Pipinstall Pulse

Install package(s)

Default:

False

Uninstall (Pipuninstall) op('python_manager').par.Pipuninstall Pulse

Uninstall package(s)

Default:

False

Update (Pipupdate) op('python_manager').par.Pipupdate Pulse

Update package(s)

Default:

False

List Packages (Listinstalledpackages) op('python_manager').par.Listinstalledpackages Pulse

List all installed packages

Default:

False

Export requirements.txt (Createreqtxt) op('python_manager').par.Createreqtxt Pulse

Export installed packages to requirements.txt

Default:

False

Install from File (Pipinstallfromlist) op('python_manager').par.Pipinstallfromlist Pulse

Install packages from requirements file

Default:

False

Requirements File (Requirementsfile) op('python_manager').par.Requirementsfile File

Path to requirements.txt file

Default:

"" (Empty String)

Utilities / Debug Header

Print sys.path (Printsyspath) op('python_manager').par.Printsyspath Pulse

Print current sys.path to textport and logger

Default:

False

Print Python Info (Printpythoninfo) op('python_manager').par.Printpythoninfo Pulse

Print venv info, CUDA, and packages to textport

Default:

False

Upgrade pip (Upgradepip) op('python_manager').par.Upgradepip Pulse

Upgrade pip to latest version

Default:

False

Show Console (Showconsole) op('python_manager').par.Showconsole Toggle

Show console window for operations

Default:

False

Block Thread (Blockthread) op('python_manager').par.Blockthread Toggle

Wait for operations to complete

Default:

False

Show Popups (Showpopups) op('python_manager').par.Showpopups Toggle

Show popup notifications

Default:

False

Environments

On Seq Remove (Seqremoval) op('python_manager').par.Seqremoval Menu

What to do when a venv is removed from the sequence

Default:

auto

Options:

auto, keep

Venv (Venv) op('python_manager').par.Venv Sequence

Default:

0

name (Venv0name) op('python_manager').par.Venv0name Str

Default:

"" (Empty String)

path (Venv0path) op('python_manager').par.Venv0path Folder

Default:

"" (Empty String)

import (Venv0import) op('python_manager').par.Venv0import Toggle

Default:

False

open (Venv0open) op('python_manager').par.Venv0open Pulse

Default:

False

Status (Venv0status) op('python_manager').par.Venv0status Str

Default:

"" (Empty String)

Changelog

v1.2.02026-03-26

• Add .gitignore (ignore __pycache__, pyc, TD artifacts)
• Defer sequence-dependent init by 1 frame to fix TD 2025 param reset on __init__ - Fix parameter existence checks to use is not None instead of truthy test
• Three-tier JSON config system (user / project folder / project DAT) - Sequence is now display-only, rebuilt from JSON config on init - New python_config_storage.py storage module - User tier: {AppData}/ChatTD/python_config.json (machine-specific) - Folder tier: {project.folder}/.lops/python_config.json (portable, relative paths) - Project tier: text DAT in operator (travels with .toe) - Auto-migration from legacy sequence entries to user JSON - Configlocation, Configpath, Refreshregistry, Editconfigfile parameters - Import toggle is runtime-only (not persisted to JSON) - Status field shows [tier] label and stale path warnings

v1.1.22026-03-01

• Fix crash when project is transferred between computers - Validate venv paths exist before importing on init - Wrap init sequence in try/except so extension loads even with invalid paths - Skip missing venvs with WARNING instead of crashing
• Auto-import venvs with import=True to sys.path on init - Fixes venvs not being added to sys.path on project open

v1.1.12026-01-28

• Add auto-registration, deduplication, and UV fallback

v1.1.02026-01-28

• Rename class to PythonExternalLibExt for backwards compatibility
• Initial commit

v1.0.02025-12-16

## Initial Release - Python Environment Manager

First standalone release of Python Environment Manager, evolved from the original ChatTD/python_manager component.

Key Features

Dual Backend Support

• UV Backend (Default) - Fast package manager with automatic Python version management
• 10-100x faster than pip for package operations
• Automatic Python download (no system Python required)
• Better PyTorch/CUDA index handling
• Venv options: Isolated (default), Seed, System Packages, Relocatable
• pip Backend - Standard Python venv with system Python detection
• Auto-detects compatible Python installations matching TD version
• Custom Python selection via dropdown menu

Environment Registry

• Register multiple virtual environments via sequence parameters
• Switch between environments using Selectedenv dropdown
• Per-environment import toggle (add/remove from sys.path)
• Automatic status display showing import state and Python version
• Auto-cleanup of orphaned sys.path entries when environments removed

VenvCore Module

• Extracted stateless venv operations to venv_core.py
• External API: pm.venv.create_venv(), pm.venv.install_packages(), etc.
• All methods take explicit venv_path - no global state
• Enables other operators (SAM3, Florence) to manage isolated venvs

Package Management

• Install/Uninstall/Update packages
• List installed packages with versions
• Export to requirements.txt
• Install from requirements file
• Upgrade pip

Utilities

• Print sys.path with venv position indicator
• Print comprehensive Python/CUDA info
• Open console with venv activated
• Run Python scripts in venv context
• Run shell commands in venv context

Backwards Compatibility

• All original Pipinstall(), Pipuninstall(), Createvenv() methods preserved
• Works as drop-in replacement for existing workflows

Architecture

```

PythonEnvManagerEXT (TD interface, parameters, callbacks)

└── VenvCore (stateless operations, subprocess calls)

```

Parameters

• Python Env Page: Status, Selected Environment, Base Folder, Backend, Python Version, Venv Options, Package Management, Utilities
• Environments Page: Sequence removal behavior setting
• Resetop() clears sequence registry (sets numBlocks=1, clears index 0)

Related Operators

• Chat