Python In TouchDesigner

TouchDesigner uses Python for scripting tasks. A custom Python build is included, with most of the features of a standard Python installation and a huge number of tools and utilities specific to working in the software.

In addition to these links, a number of working examples can be accessed by selecting Help -> Python Examples in the TouchDesigner UI.

Learning Python

If you don't know Python, here are some good resources for learning:

Python Classes and Modules Available in TouchDesigner

TouchDesigner includes all the modules in a standard Python installation plus the following:

td: TouchDesigner's Main Python Module

All td module members and methods are available in scripts, expressions, and the textport. There is no need to import the module or its members explicitly. This is especially important in expressions, which don't allow import statements.

The following can be found in the td module:

  • Main TouchDesigner utilities - the most basic starting points for interacting with TouchDesigner, such as me and op().
  • TouchDesigner Python helper classes - important helper objects used to organize functions and information pertaining to a specific part of TouchDesigner.
  • Operator related classes - every Operator in TouchDesigner has an associated Python class in the td module. Their wiki pages can be accessed by clicking on the Python Help button in their parameter dialog. There are also a number of associated Python objects that are used when working with Operators.
  • Useful standard Python modules - the td module also automatically imports a number of helpful standard modules (e.g. math), allowing them to be accessed in expressions through their namespace.

TouchDesigner Utility Modules

TouchDesigner also contains utility modules for advanced Python programming. Utility modules are not imported into the td module automatically. Instructions for their use can be found on their wiki pages.

3rd Party Packages

TouchDesigner includes a number of 3rd party Python packages that are generally useful when working with the software. These are not included in the td module so must be imported explicitly.

Installing Custom Python Packages

Part of the great power of Python is its access to the countless number of modules that have been created. If you want to use modules that are not included in the above, use the following steps:

  1. Install a parallel copy of the same version of Python that your TouchDesigner is using.
    1. To determine what version of Python is installed with TouchDesigner, enter the command sys.version in a Textport.
    2. Download that version. You can find it in the list here in the section labeled "Looking For A Specific Release?".
    3. Install Python. Be sure to select the "Add Python ___ To Path" option in the installer. If you don't do this, you can add the path manually by following these instructions.
  2. Install your custom Python package, following its normal installation procedure. Some packages may have special installation procedures, but most will be a simple command like pip install <package name>. Enter this command in the Command Prompt (on Windows) or the Terminal (on Mac), not at the Python prompt.
  3. Launch the Python application and import the module manually to make sure there are no errors. This is usually done by entering import <package name> at the Python prompt. If you don't see an error message, your package is installed successfully.
  4. The module will automatically be visible in TouchDesigner as long as "Add External Python to Search Path" is on in Preferences. This option is on by default. To test, open a Textport and enter import <package name>. Again, if there are no errors, your package is installed and you can now import it and use it in TouchDesigner Python scripts.

Other Ways to Customize Your Python Path

You can add the search path by modifying the Preference labelled "Python 32/64 bit Module Path". Multiple paths are separated by semicolons (;). Finally you can modify the search path directly by either modifying the system environment variable PYTHONPATH or by executing a script which appends the path to sys.path as in the example below.

import sys
mypath = "C:/Python37/Lib/site-packages" # be sure to use your actual Python installation location if it's different
if mypath not in sys.path:

Examples of other useful Python modules are here. Unofficial precompiled modules found on Christoph Gohlke's website.

Overriding Built-In Modules

TouchDesigner comes with many specific modules pre-installed. If you require a different version, find the TouchDesigner folder where the original is included and remove it from the search path before importing. For example:

import sys
sys.path.remove('C:\\Program Files\\Derivative\\TouchDesigner\\bin\\lib\\site-packages')

Python Gotchas

There are a few things in standard Python that can trip you up in TouchDesigner. If you find anything that's not included here, post in the forum!

  • Some TouchDesigner objects (especially parameters and CHOP channels) will try to act as the correct data type for their context. For example, a Float parameter object (myOp.par.Float1) will act like a floating point number in most cases, but it is still a parameter object. For example round(myOp.par.Float1) will not work. To get the actual value of a parameter or channel, use its .eval() method. If you think you may be encountering this problem, you can tell the difference by using the repr function. For example repr(myOp.par.Float1) will show that this is a parameter and not a number.
  • same goes with operator parameter types. if a parameter is a path to a CHOP, n.par.Chop usually works, but to be safe, n.par.Chop.eval() always works.
  • subprocess.Popen doesn't work with file-like objects. See this forum post for details.
  • Python threads don't have access to TouchDesigner objects. Search "threading" in the forum to see some workarounds.

More In The Python Category