Introducing the TouchDesigner Python Environment Manager (TDPyEnvManager)
2 Likes
Iâm kinda new to utilizing rather in-depth Python functionality in TD and not quite sure if this is the right place to ask this question, but Iâm guessing that newbies like me are likely to be coming across the same obstacle, so here goes the question.
I used Alphamoonâs TD pip tox file to implement a similar virtual python environment for incorporating âeasyocrâ library into TD, which requires numPy and other basic libraries with later versions than the ones used by the native python that comes with the TD version Iâm using(2023.12120).
Iâve successfully imported the âeasyocrâ into my TD under the new python virtual environment, but it crashes as soon as a Script TOP cooks. (Which utilizes numPy, and I suspect the version mismatch to be the cause)
Could TDPyEnvManager run simultaneously along with the native TD python side by side without any compatibility issues? Or at least switch back and forth to avoid any collision?
Taking the most out of both TD and external Python functionality simultaneously would be an ideal world for me, really, but Iâm not sure if thatâs something possible at this point, thoughâŚ
Hey @barmoon7
The issue you are facing is a known issue and indeed caused by a version mismatch with NumPy in TouchDesigner builds 2023.12120 and above, on that specific branch.
The issue is fixed in current experimental builds 2025.30k+.
To answer your question, not really.
The TDPyEnvManager is designed to create virtual environments out of TouchDesignerâs own Python, which guarantee the same python version to be used and link back to the same python interpreter.
When using the Conda mode, this is also designed to create conda environments matching TouchDesignerâs own Python version, to maximize compatibility and avoid some version mismatch issues.
You could use the conda mode to run both TouchDesigner, and another Python process, in parallel, but you would have to design the whole data exchange between both processes.
Best,
Michel
Thanks for the quick reply! but could you clarify on how the issue is fixed?
No matter what the version of Python a certain TD version runs, itâs still bound to that one specific Python version isnât it? So, under my understanding, there still lies a possibility of TD crashing as along as the numPy version of the newly incorporated venv Python does not match the numPy version of the Python native to TD.
I suppose the experiment builds come with relatively version of new Python/numPy/etc, but theyâll get outdated at some point or if I need to use libraries that use older versions of numPy/etc, the version mismatch is still there in either case no?
Iâm curious if TDPyEnvManger can be run via an Engine COMP so it can be run on a separate thread and never collide with the main TD project and if that doesnât work, I guess Iâll have to run two separate TDs and let them comm. through OSC or something instead.
In any case, Iâm really grateful for your contribution to the TD and it will benefit everyone in so many ways really!
Itâs unlikely that the crash would occur, as this is the fixed issue here and if itâs erroring because of this, itâs clearly stated in the info dialog.
I suppose the experiment builds come with relatively version of new Python/numPy/etc, but theyâll get outdated at some point or if I need to use libraries that use older versions of numPy/etc, the version mismatch is still there in either case no?
Yes, builtin packages were updated with experimental.
If they get outdated, you are free to sideload a vEnv using the TDPyEnvManager and upgrade the package you wish to be upgraded. In most cases, if itâs a minor version update, this would not cause issues.
If you need to use libraries that use an older version, and where the version requirement is that strict, then Iâd suggest to ask the library developers to do the update, or tweak the requirements to be a bit more permissive if at all possible. Last, you can run this in parallel to TouchDesignerâŚ
Iâm curious if TDPyEnvManger can be run via an Engine COMP so it can be run on a separate thread and never collide with the main TD project and if that doesnât work, I guess Iâll have to run two separate TDs and let them comm. through OSC or something instead.
No. The Engine COMP still run the same python interpreter that ships with TouchDesigner. There is no way around that.
Python is tightly integrated to TouchDesigner. The builtin libraries we ship are production tested, and tightly integrated within multiple parts of TouchDesigner. The TDPyEnvManager just makes things easier to work around and more permissive.
But this is not a magic solution that works around TouchDesignerâs own architecture and Pythonâs best practices.
Thanks for the reply and your support! Youâve cleared up a lot of the question marks I had about TD!
Another great addition to TD!
Exactly when I need it, perfect timing 
I try it right now, thanks a lot for your work!
2 Likes
Is it possible to link an existing venv?
For our project, TD is part of the setup, but not necessarily the main component - thus we develop and create code in a venv which weâd like to use in TD. Right now weâd just specify it in the settings, but being able to use this component would be great. However, it looks like this only supports creating a new venv?
Hi @timlod - Itâs a tricky one because TouchDesigner creates the vEnv using the exposed method in the vEnv library. In python, what it does is that it binds the python vEnv to the python interpreter it was created from. For TouchDesigner, that interpreter is in the TouchDesigner installation. This ensure that the Python installation match versions, core libs, etc.
Stated in the vEnv official doc is the following, which, I think, applies here.
If for any reason you need to move the environment to a new location, you should recreate it at the desired location and delete the one at the old location. If you move an environment because you moved a parent directory of it, you should recreate the environment in its new location. Otherwise, software installed into the environment may not work as expected.
While doing testing, what we observed is that Python does write some absolute paths in some places and itâs only safe to recreate your vEnv.
The safest would be to create your vEnvs using the TouchDesigner Python interpreter at all time.
We are opening up a bit while working on the following RFE: Open up TDPyEnvManagerContext.json
But vEnvs that are not created with the TouchDesigner Python Interpreter or TDPyEnvManager might have some issues.
In the meantine you can look at this repository which, despite the name, is not at all dependant on uv and env agnostic.
The trick lies in this script which you place in a TextDAT in /local/modules called sys, overwriting the default sys behaviour.
It will then read each line from .packagefolder and add it to sys.path in time.
Note that this is a hack and not guaranteed to not break stuff, but at least for me we are using this project prefab actively in production with huge success.
In the most recent 2025.31760 build on Windows 11 I get a multitude of errors, making TDPyEnvManager unusable. I cannot get rid of this even after reinstalling Touchdesigner.
I have attached some screenshots that show my issues.
For some reason the tdPyEnvManager COMP also resets itself after some time and is âback to normalâ, but the time until this happens is always different
Hi @v.rtx_void Can you create a folder and save a .toe file then retry?
1 Like
Using Wielandâs hack for 2023 and TDPyEnvManager for 2025, this problem finally feels solved, and the auto setup is EXCELLENT.
Props to @JetXS for this and being flexible with requested changes!!
1 Like