Introducing the TouchDesigner Python Environment Manager (TDPyEnvManager)

As of 2025 experimental builds, TouchDesigner is shipping with a new Palette component aimed at improving and easing interaction between TouchDesigner and sideloaded python environments.

Building upon the foundations of a popular approach from our article covering Anaconda usage, we are streamlining the experience with a new dedicated component.

Introducing the TDPyEnvManager COMP

The TouchDesigner Python Environment Manager COMP or TDPyEnvManager COMP is designed to become your homebase when working with sideloaded Python environments and third party libraries. We aim at making it the trusted go-to solution for TouchDesigner users and advanced developers.

The TDPyEnvManager COMP is a custom component that helps manage Python environments (vEnv) as well as Conda environments, the primary focus is for sideloading environments and integrating third party libraries more easily in TouchDesigner.

!!! Sideloading Python environments and third party packages is at your own risk and can cause instabilities. For more details, head to https://docs.derivative.ca/Python

Users can create, activate and interact with Python vEnvs and conda environments from the component's parameter dialog. Users can interact directly with pip in both vEnvs and conda CLIs, as well as conda commands when using conda.

Some additional features are built-in such as exporting requirements.txt and environment.yml files, and conversely creating environments from requirements.txt or environment.yml files.

Created environments are immediately added to the TouchDesigner search path.

!!! With the complexity of covering multiple systems (ie. Windows, MacOS, and environments from Python and Conda), comes the complexity of testing. Some edge cases might not be covered and we are inviting the community for feedback. If you find that you are missing a feature, or that an implemented feature might need a change or some UX improvements, feel free to send us a message in the forum.

Using TDPyEnvManager with Python vEnv

Using Python virtual environemnts (vEnv) is the default setup when using the TDPyEnvManager. While we could support management of multiple vEnvs, the idea here is to enable for only one vEnv per project folder with a limited set of features for a common and streamlined approach.

Let’s get started.

Create a new folder and name it MyTDEnvTest.

Let’s create at the root of MyTDEnvTest a .toe file named MyTDEnvTest.toe. Then open this new .toe file. Delete any OPs in /project1.

Go in the palette and drag n drop TDPyEnvManager from the Tools folder.

First, turn on the component by toggling on the Active toggle. This toggle is handy when you have already setup an environment but you want to prevent it from being added to the TouchDesigner search path on startup for debugging purposes or prototyping.

You’ll see a dialog with a disclaimer stating that sideloading environments and using third party libraries in TouchDesigner is at your own risk. You can click continue if you are fine with the disclaimer.

Now, we don’t have much settings to cover to have a working setup.

For Python vEnv to be streamlined and straightforward, you can simply click on Create vEnv to get going.

The vEnv will be following the same naming schemes on all machines. It will use the project folder name and add the suffix _vEnv after it.

So, in our case, a folder MyTDEnvTest_vEnv will be created in MyTDEnvTest next to MyTDEnvTest.toe.

When you click on the pulse parameter, you will see an animation in the viewer of TDPyEnvManager, as well as the Status parameter in the parameter dialog updating.

After a few seconds, the creation of the vEnv will be done and you should see in the Status the message Environment linked and ready.

You can go down and click the pulse the parameter on Open CLI: it will open a new terminal, with the vEnv you just created being activated.

Let’s try and install a simple library missing from TouchDesigner.

In the new terminal window, let’s type pip install zmq. It will look for the zmq package on PyPi and download and install it in the vEnv.

You can close the terminal window.

In TouchDesigner, in the textport (Alt+T), type import zmq followed by zmq. It will import zmq and show in the textport the zmq module as well as where it’s loaded from.

If everything went well, you should see that zmq was loaded from wherever you created your MyTDEnvTest folder: MyTDEnvTest/MyTDEnvTest_vEnv/Lib/site-packages/zmq/__init__.py

You can now use this new package in TouchDesigner.

! A note about UV - If trendy UV is your preferred tool, you can install it within your vEnv using pip install uv You can then use uv your_command in the running CLI.

Sharing my vEnv setup with others

Sharing vEnv setups is fairly straightforward. Click on the parameter pulse Export requirements.txt

This will create a requirements.txt file next to your currently running .toe file.

!!! Important note: This is not an optimal requirements.txt file. You need to go through it manually and curate it to avoid setting too many version restrictions and possibly add a --extra-index-url <https://some.url> line within the requirements.txt file.

Share this requirements.txt with another user.

They just have to have this requirements.txt file next to the .toe file they have open, and when they click on Create from requirements.txt it will create a vEnv and install all the required packages, such as zmq.

! If a matching folder of the same name is already present, the folder doesn’t get cleared. The environment gets created if a file is missing in the target folder, but an existing environment will be unaffected unless there is a change in dependencies caused by the Python builtins or a possible requirements.txt file being present. This is valid for both creating a barebone vEnv from TouchDesigner or creating a vEnv with a requirements.txt file being present.

Using TDPyEnvManager with Conda

This approach is slightly different than the builtin Python vEnv approach. We are using conda and the Miniconda installer. On top of allowing for conda packages to be installed (as well as pip packages), we can specify the conda install folder in which environments will be looked for and created, we can create multiple conda environments, and list conda environments that are installed on the machine globally. Similar to the Python vEnv approach, we can export our environment.yml files and create environments from environment.yml files.

!!! When using the conda mode, TouchDesigner is downloading and installing the Miniconda installer in the background. When silently installing the Miniconda installer, users agree to the Anaconda Inc. ToS: https://legal.anaconda.com/policies/en/

TouchDesigner adds restrictions so that environments created are setup to fetch packages from conda-forge channels, which are not the default channels covered by the Anaconda Inc. ToS. However, there is a probability for user or system configurations to take priority and the restrictions might not always apply.

Creating and activating a `conda` environment

We will start in a new empty folder, with a new .toe file.

From the palette, drag and drop the TDPyEnvManager

Turn the Active parameter on, and click Continue in the popup with the disclaimer.

Select Conda Env in the Mode parameter.

For the purpose of this demo, we will create a new Miniconda installation from scratch.

Keep the Conda Install Folder parameter as is.

In the Environment parameter, type the name of the environment you want to create. I’ll name mine MySuperCondaEnv.

You can now click on the pulse par Create Conda Env.

It’s going to take a few minutes: the Miniconda installer is being downloaded relative to your .toe file. Once it’s downloaded, it will start the installation.

The installer is fairly small so it should be downloaded quickly.

! If you are working offline and already downloaded the Miniconda installer, place it next to your .toe file and click on the toggle Keep Conda Installer. It will re-use the installer and keep it after install. On Windows, you can find the installer at the following link: https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe. Keep it named Miniconda3-latest-Windows-x86_64.exe. On MacOS, you can find the installer at the following link: https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh. Keep it named Miniconda3-latest-MacOSX-arm64.sh.

Before starting the installation, you’ll be prompted with a dialog to let you know of Anaconda Inc. ToS.

image (2)_1.png — Anaconda ToS Prompt in TDPyEnvManager

Click on Continue to proceed.

The installation will start and run silently.

If any problems occur during the installation, it will be printed in the textport. Once the installation is done, conda will proceed and create a new environment.

Once the installation is done and the environment is created, you’ll see in the status message that the environment is linked and ready to be used.

Now, you can proceed and click on the Open CLI pulse parameter to open the conda prompt with your activated environment.

In my case, where I’ve named the environment MySuperCondaEnv, I see the CLI input being preceded by the (MySuperCondaEnv) which indicates which environment is activated.

From this prompt, you can use any conda commands, such as conda install as well as pip commands.

I’ll install the popular progress bar library, tqdm with conda install tqdm.

After installation, I can go in TouchDesigner’s textport and type import tqdm followed by tqdm and see that my package is properly installed and imported from my MySuperCondaEnv environment.

Listing global environments

Granted we have installed Miniconda or we are pointing to a valid, already installed conda install, toggling on the Include Global parameter will list all environments on the machine with a Python version matching TouchDesigner’s. Global environments are in the dropdown menu of the Environment parameter and are suffixed by a star *.

Sharing my `conda env` setup with others

You can click on the parameter pulse Export environment.yml and an environment.yml will be created, relative to your .toe file. The difference with a Python requirements.txt file is that it includes the Python version as a requirement to the environment created, the environment name, as well as packages of various sources and the channels in use.

You can share this file with another user for them to create a matching environment. They can add the environment.yml file next to the .toe file they are currently using and click on the Create from environment.yml pulse parameter.

!!! Note that if a matching environment already exists, it will be overridden by the environment.yml requirements.

Advanced usage

The approaches above are all done through the parameter dialog and the CLI.

If you want more control on the creation process and installation, you can use the TDPyEnvManager programmatically using its extension promoted attributes and methods, or you can use the TDPyEnvManagerHelper directly. The TDPyEnvManagerHelper can be used as a module and imported from the TDPyEnvManager COMP/TDPyEnvManagerHelper or as an attribute of the TDPyEnvManager itself, Helper.

Last, you can interact with the Helper using a CLI without running TouchDesigner: go in your TouchDesigner installation and find the Samples/TDPyEnvManager folder for samples.

More details are available in the wiki on the extension page and on the Helper page.

Considerations

When using the TDPyEnvManager in your projects, and when custom components are relying on third party libraries loaded from side loaded environments, it is preferable that you let the initialization of custom components being handled lazily.

i.e. Do not force initialization of components using an Execute DAT or the Init On Start toggle.

The TDPyEnvManager should be the first component initializing on start so that the environment is setup before any additional component attempt to import modules from it.

To fail initialization gracefully, you can add a try / except condition around your import statements at the top of your extension.

try:
	import tensorrt as trt
	import torch
	import torchvision.transforms as transforms
except Exception as e:
	logger.error(f'TDDepthAnythingHF - An error occured trying to import some of the required libraries. Make sure that the environment is setup properly.')
	logger.error(f'TDDepthAnythingHF - {e}')

When setting up your TDPyEnvManager and side environment, you can safely ignore issues from custom components. When your environment is setup properly and you installed the required dependencies, restart TouchDesigner and any import issue should be fixed.

Tips

When developing using VSCode (or another editor of your choice which ships with matching features), you can setup your code-workspace to load both TouchDesigner TDI library as well as the libraries installed in the sideloaded environment:

{
	"folders": [
		{
			"path": "."
		}
	],
	"settings": {
		"python.defaultInterpreterPath": "C:\\Program Files\\Derivative\\TouchDesigner.2023.32465\\bin\\python.exe",
		"python.analysis.autoSearchPaths": true,
		"python.autoComplete.extraPaths": [
			"C:\\Program Files\\Derivative\\TouchDesigner.2023.32465\\bin\\python\\Lib\\site-packages",
			".\\scripts",
			".\\TDDepthAnythingHF_vEnv\\Lib\\site-packages",
		],
		"python.analysis.extraPaths": [
			"C:\\Program Files\\Derivative\\TouchDesigner.2023.32465\\bin\\python\\Lib\\site-packages",
			".\\scripts",
			".\\TDDepthAnythingHF_vEnv\\Lib\\site-packages",
		],
	}
}

In the example above, the interpreter is pointing to TouchDesigner’s own Python binary and we added TouchDesigner site-packages as well as a Python vEnv plus a relative scripts folder.

Conclusion

That’s a wrap for our introduction to the TDPyEnvManager.

For a concrete use case, jump to the the following article, we’ll be using the TDPyEnvManager and the Thread Manager to work with the Hugging Face transformers library and Depth Anything V2.

Privacy policy

Follow us

Introducing the TouchDesigner Python Environment Manager (TDPyEnvManager)

Introducing the TDPyEnvManager COMP