Saving & Sharing Projects

The .toe File

Everything in a TouchDesigner project — every operator, every parameter value, every Python script, every wire — is stored in a single .toe file (TouchDesigner Project File). The .toe format is binary and compressed. You cannot meaningfully open or edit it in a text editor, but it is a self-contained bundle of your entire network.

Saving: Press Ctrl+S at any time. If the file has not been saved before, a system file browser opens so you can choose a location and filename. After the first save, Ctrl+S updates the existing file in place.

Save As: File > Save As (Ctrl+Shift+S) opens the file browser regardless, letting you save to a new location or under a new name. Use this for versioning.

Save a Copy: File > Save a Copy writes a copy to a new path without changing the currently open file’s path. Useful for snapshots without interrupting your working file.

TouchDesigner does not auto-save. Develop the reflex of pressing Ctrl+S every few minutes, especially before making significant changes to a network. Crashes are rare but they happen, particularly when a GPU shader goes wrong.

External Assets and Relative Paths

The .toe file does not embed external assets like video files, images, audio files, or 3D models. These are referenced by file path. If you move the .toe file without moving its assets, the references break and you will see errors when you reopen the project.

Use relative paths. A relative path is expressed relative to the location of the .toe file. In a Movie File In TOP’s File parameter, instead of:

C:\Users\yourname\Projects\ShowA\assets\video\background.mov

Use:

assets/video/background.mov

TouchDesigner resolves this relative to the .toe file’s folder. On macOS use the same forward-slash convention.

Check what you have: Go to File > Assets (in some builds, Dialogs > Project Assets) to see a list of all externally referenced files and whether they are currently found.

Recommended Project Folder Structure

A clean folder structure prevents asset-path headaches when moving projects between machines or sharing with collaborators:

ShowA/
├── ShowA.toe
├── assets/
│   ├── video/
│   │   └── background.mov
│   ├── images/
│   │   └── texture_01.png
│   └── audio/
│       └── music.wav
├── data/
│   └── config.json
└── python/
    └── helpers.py

With this structure, all asset references in the .toe file use paths like assets/video/background.mov. Anyone who receives the entire ShowA/ folder can open the project immediately without path adjustments.

Saving Versions

TouchDesigner has no built-in version history. Develop a manual versioning habit:

Date-numbered files:

ShowA_2025-11-01.toe
ShowA_2025-11-03.toe
ShowA_2025-11-03b.toe

Build-numbered files:

ShowA_v001.toe
ShowA_v002.toe

Keep old versions around until the project is over. Disk space is cheap and one accidental save-over can cost hours of work.

A good ritual: at the start of each working session, do a Save As with today’s date before making any changes. That way your starting state is always preserved.

Git for TouchDesigner

Since .toe files are binary, standard Git diff and merge tools are useless on them. But Git is still valuable for:

• Keeping a full history of binary snapshots.
• Coordinating which version is “current” in a team.
• Triggering CI/CD pipelines for automated deployment.

Setting up Git:

1. Initialise a repository in your project folder: git init
2. Add a .gitattributes file in the project root:

*.toe binary
*.tox binary
*.jpg binary
*.png binary
*.mov binary
*.mp4 binary

Marking .toe and .tox as binary prevents Git from trying to diff them as text (which would produce garbage output) and prevents Git’s line-ending normalisation from corrupting the files.

1. Add a .gitignore to exclude temporary files TouchDesigner creates:

*.bak
Backup/
__pycache__/
*.pyc

1. Commit your .toe and assets/ directory as normal. Each commit is a full snapshot. You cannot merge two people’s changes to the same .toe file — TouchDesigner projects are single-author files at the binary level.

For teams: use branches and establish a clear handoff protocol. One person works on the file, commits, pushes. The other pulls. Do not have two people editing the same .toe simultaneously.

Sharing on the Derivative Forum

The Derivative forum at derivative.ca/forum is the primary community hub. When sharing work or asking for help, you have two options:

Share the .toe file directly. Zip the entire project folder (.toe + assets) and attach it. This is the most complete option and the easiest for someone to open and explore.

Share a .tox component. If the problem or the demonstration is contained within a single component, save just that component as a .tox file. This is smaller, works with any project, and is the standard format for the TouchDesigner community toolkit on Github and package repositories.

The .tox File: Shareable Components

A .tox file is a serialised COMP (component operator). It contains the entire sub-network of that COMP, its parameters, and any embedded assets. You can drop a .tox into any project’s Network Editor and it will instantiate as a working component.

Saving a .tox:

1. Right-click the COMP you want to save.
2. Choose Save Component .tox.
3. Choose a location. Conventionally, .tox files live in a components/ or lib/ subfolder of your project.

Loading a .tox:

1. Drag the .tox file from your system file browser into the TouchDesigner Network Editor.
2. It instantiates as a COMP with all its internal network intact.
3. Alternatively, go to the Palette Browser and add your components folder as a custom palette category.

Designing for .tox reuse: If you intend to share a component as a .tox:

• Use Custom Parameters on the COMP to expose the important controls at the top level (right-click the COMP → Customize Component → add parameters).
• Use relative op() paths inside the component so it is self-contained.
• Avoid hard-coded absolute paths to assets; either embed assets as externally-stored data URIs or document the expected asset folder structure.

The Palette as a Personal Library

The Palette Browser on the left side of the screen can display your own .tox files alongside the built-in palette:

1. Click the + button at the top of the Palette Browser.
2. Navigate to a folder that contains your .tox files.
3. The folder appears as a custom category in the Palette.

Now you can drag your reusable components directly from the Palette into any project — exactly like using the built-in tools. This is how experienced practitioners build up a personal library of tested components (a smooth audio reactive trigger, a projection-mapping calibration tool, a MIDI mapping UI) that they drop into every project.

Packaging for Delivery

When handing a project off to a venue or a collaborator who will run it on a different machine:

1. Open File > Assets and resolve any broken references.
2. Zip the entire project folder including all assets.
3. Document any external hardware dependencies (capture cards, MIDI controllers, Kinect, etc.) in a README (or a Text DAT inside the project).
4. Include the TouchDesigner build version that the project was developed and tested with. The person receiving the project should install that exact build or the nearest stable build.
5. Test the zip by extracting it to a different folder and opening the .toe from the extracted path. This catches any remaining absolute paths.

With your project saved and shareable, the final tutorial covers what to do when things go wrong — diagnosing errors, fixing dropped frames, and tracking down common pitfalls.