Skip to content

Installation

Theia installs in two parts: a Python environment and GUI scripts under /Library/Application Support/Theia, and a set of small "bridge" scripts that tell DaVinci Resolve how to launch each tool from its Scripts menu. A single installer handles both.

Prerequisites

Before you run the installer, make sure you have:

Requirement Notes
macOS The installer is macOS-only.
DaVinci Resolve Studio The free version of Resolve does not include the scripting API that Theia depends on.
Python 3.9 or newer On Apple Silicon Macs, Homebrew Python is recommended (brew install python).
ffmpeg Used by Frame Counter to embed timecode metadata. The installer can install this for you via Homebrew if it's missing.

You don't need to know how to code to install or use Theia — the installer is a double-clickable script, and every tool is a normal point-and-click window.

Step 1: Enable Resolve's scripting API

Theia talks to Resolve through its scripting API, which needs to be set up once per machine:

  1. Open DaVinci Resolve.
  2. Go to Help → Documentation → Developer.
  3. In the folder that opens, find the Scripting folder and follow the instructions in its README.txt.

If you skip this step, Theia's tools will still open, but they won't be able to read your timeline (see Troubleshooting).

Step 2: Run the installer

  1. Download or git clone the Theia project folder to your Mac.
  2. In Finder, locate install.command inside the project folder.
  3. Right-click it and choose Open (the first time you run it, macOS may warn that it's from an unidentified developer — this is expected for a script you downloaded yourself).
  4. A Terminal window opens and walks through the install. You'll see it:
    • Check your Python version (3.9+ required) and pick the right Python — it prefers Homebrew Python on Apple Silicon.
    • Check for ffmpeg, and offer to install it via Homebrew if it isn't found.
    • Ask for your administrator password, so it can create /Library/Application Support/Theia.
    • Create a private Python virtual environment in that folder and install Theia's dependencies (PySide6, openpyxl, Pillow, timecode).
    • Copy the four GUI scripts and the resources/ folder (fonts, icons) into /Library/Application Support/Theia.
    • Copy the four bridge scripts into Resolve's Edit-page script menu folder, at: /Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Edit/Theia.
  5. When you see "Installation Complete!", you're done. You can close the Terminal window.

Apple Silicon and Rosetta

The installer detects whether your Python is running natively as ARM64 or under Rosetta as x86_64, and installs packages for the matching architecture automatically. If you hit architecture-related errors, reinstalling with Homebrew Python (brew install python) usually resolves it.

Step 3: Confirm the tools appear in Resolve

  1. Open (or restart) DaVinci Resolve.
  2. Open any project and go to the Edit page.
  3. Go to Workspace → Scripts → Edit in the menu bar.
  4. You should see four entries, one per tool:
    • 01 Clip Inventory
    • 02 Frame Counter
    • 03 Add Metadata
    • 04 Shot List

If the menu is empty or missing entries, see Troubleshooting.

Multiple users on one machine

Each person who wants to run Theia from their own Resolve needs to run install.command once under their own macOS user account, since the bridge scripts and Python environment are installed per-user.

Updating Theia

Re-running install.command is safe — it removes and recreates the virtual environment and overwrites the copied scripts, so it always leaves you with the latest version from the project folder you ran it from.

Uninstalling

A matching uninstall.command ships alongside the installer. Double-click it (or right-click → Open), confirm with y when prompted, and it removes:

  • /Library/Application Support/Theia (the Python environment, GUI scripts, and resources)
  • /Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Edit/Theia (the bridge scripts)

It does not touch any Excel files, frame counter videos, or other output you've generated — those live wherever you saved them.