DaVinci Resolve Python Scripting: The Complete Guide to the API

Most colourists open the Scripts menu once, see a Lua example they don’t understand, and close it. Then they spend the rest of the week manually building render queues, relinking media, and duplicating timelines for every version of every deliverable.

DaVinci Resolve’s Python API can automate all of it. Not in theory — in practice, on real documentary projects, on deadline. But the official documentation is a plain-text README with no examples and no tutorial. The gap between “scripting is possible” and “scripting is useful” is where most finishing professionals stop.

This guide closes that gap. It covers the full DaVinci Resolve Python API — what it can do, what it cannot, how to set it up correctly, and the practical scripts that deliver the highest return in a finishing workflow. Everything here is verified against the Resolve 20.3 API documentation and tested in production.

Why Python, not Lua

Resolve supports two scripting languages: Lua (built in, no setup required) and Python (external install, full pip ecosystem). Lua works in both the free and Studio versions. Python requires Studio.

For anything beyond simple console one-liners, Python is the practical choice. The reason is ecosystem: opentimelineio for timeline interchange, pandas for metadata manipulation, pathlib for cross-platform file management, and the ability to connect Resolve to external tools — QC platforms, MAM systems, AI services — via standard Python libraries. Lua cannot do any of that.

If you are running DaVinci Resolve Studio (and at a professional level, you should be), use Python.

Setting up the DaVinci Resolve Python API

This is the step where most guides fail you. The setup is not obvious, and Resolve is completely silent when the environment is misconfigured — scripts just fail with cryptic import errors.

Python version: Install Python 3.10–3.12 from python.org. Not Homebrew, not the Microsoft Store. Python 3.13+ introduces ABI changes that can cause crashes with Resolve’s fusionscript library.

Three environment variables are required. Resolve does not add itself to your Python path — you must do it manually. On macOS you need to point to the Scripting folder inside Application Support, the fusionscript.so library inside the Resolve app bundle, and the Modules subfolder. On Windows the paths follow the same logic under ProgramData and Program Files. Add these to your shell profile so they persist across sessions.

Resolve must be running and a project must be open before any script can connect. The scriptapp(“Resolve”) call returns None if Resolve is not running — always check this before your script proceeds.

Running scripts: From the terminal, execute your .py file with the environment variables set. From inside Resolve, place scripts in the Workspace > Scripts menu directories and launch them from there.

Important: External script execution requires DaVinci Resolve Studio. The free version limits scripting to the internal console only. Since Resolve 19.1, UIManager-based script GUIs are also Studio-only.

The API object model: how Resolve exposes itself

The DaVinci Resolve Python API is a hierarchical object model. Every operation follows the same chain downward from a single root object — the Resolve instance. From there you navigate to the ProjectManager, then to the current Project, then to its MediaPool, Timeline, Gallery, and render queue.

Resolve 20.3 documents 14 object classes in total, covering the project manager, project settings, media storage, media pool, bin folders, individual clips, timelines, timeline items, gallery stills, and colour groups. The Graph and ColorGroup classes were formally documented in the Resolve 20 cycle.

The most important design characteristic of the API: it is almost entirely silent on failure. Methods return False or None without error messages, stack traces, or logging. This makes debugging substantially harder than in most scripting environments, and it means every return value must be checked. Defensive coding throughout is not optional — it is the only way to build scripts that hold up in production.

What the DaVinci Resolve Python API can do

Project and database management

The full project lifecycle is scriptable: create, load, save, close, delete, export as .drp, archive as .dra with media, import, and restore. The ProjectManager handles database switching across both disk and PostgreSQL databases, project folder navigation, and cloud project operations. Project settings — resolution, frame rate, colour science, and dozens of other parameters — are fully readable and writable.

Media pool and clip management

Import media, create and organise bins, move clips between folders, relink offline media, manage proxies, read and write all clip metadata, set markers, apply flags and clip colours. The MediaPoolItem class is one of the richest objects in the API — it exposes full metadata access, third-party metadata fields, markers with custom data payloads, flag management, clip colour, mark in/out points, audio channel mapping, transcription triggering, and proxy linking.

Scripting bin structures across a large documentary project — hundreds of clips organised across dozens of bins — is one of the most immediately practical uses of the API. A template structure can be replicated across every new project in seconds.

Timeline operations

Create timelines from clips or from EDL, XML, AAF, FCPXML, DRT, OTIO, and ADL files. Duplicate timelines for versioning. Manage tracks — add, delete, enable, lock, rename — across video, audio, and subtitle tracks including Atmos-compatible adaptive formats. Append clips with frame-accurate control. Create compound clips and Fusion clips. Trigger scene cut detection. Control the playhead. Export to multiple interchange formats.

The timeline import system is particularly useful for conform workflows: ImportTimelineFromFile() accepts source clip paths for auto-conform and custom timeline naming as part of the import options.

Markers: structured data for QC and review

Every object that can hold a marker — clips, timelines, and timeline items — supports full marker operations: create, read, delete by colour or by frame position, and bulk operations by colour. The customData field accepts arbitrary strings, which makes markers a lightweight structured-data store. Encoding JSON in this field lets you attach QC categories, severity levels, reviewer names, or external tool references to any frame in any clip or timeline. Markers become the bridge between Resolve and any downstream QC or review process.

Colour page: what is accessible

Colour page scripting is limited but not useless. You can apply LUTs to specific nodes, read and write ASC-CDL values (Slope, Offset, Power, Saturation) per node, apply grades from .drx stills, copy grades between clips, export grades as cube LUT files in multiple point densities, and manage gallery still albums fully — capture, export, delete.

What you cannot touch: primary colour wheels, curves, qualifiers, power windows, HDR palette, OFX plugins, and the node graph itself. You cannot create, delete, or reorder colour nodes via script. The API is useful for applying pre-built looks and round-tripping grade data, not for performing or adjusting actual grading work.

Render queue management

The render queue is fully scriptable. Add jobs, delete jobs, start and stop rendering, query render progress, load and save presets, set every render parameter (format, codec, resolution, frame rate, output directory, custom naming, quality, audio settings, colour space tags), query available formats and codecs, manage burn-in presets. This is the highest-value area of the API for professional finishing workflows.

Delivery automation: the highest-value use case

Multi-format delivery is where Resolve Python scripting delivers the most immediate return. A broadcast documentary requires delivery in multiple formats — broadcast-compliant MXF, streaming H.264 or H.265, archive ProRes — each with specific naming conventions, codec settings, and output paths. Manually queuing these is time-consuming and error-prone at the point in production when errors cost the most.

A delivery script works by iterating over a list of delivery specifications, configuring render settings for each, adding a render job, and then launching the full batch in a single call. The naming logic can incorporate series codes, episode numbers, version identifiers, and delivery dates — all generated programmatically and applied consistently across every deliverable.

For multi-timeline batch rendering — multiple episodes or multiple version cuts — you set the current timeline before each render job is added. A single script can queue an entire series across all delivery formats and start the render before you leave the desk.

One important constraint: render presets cannot be fully created from scratch via the API. Configure them manually in the Deliver page first, then save and name them. From that point, presets can be loaded, applied, imported, and exported programmatically — making it straightforward to standardise delivery configurations across multiple workstations or facilities.

What the DaVinci Resolve Python API cannot do

These are not edge cases. They are gaps that affect common finishing operations. Understanding them before you start building automation prevents significant wasted time.

Timeline editing is not scriptable. No cut, split, or razor operations exist. No trim controls — there is no way to adjust the in or out point of an existing timeline clip via script. No clip movement, reordering, transitions, fades, speed changes, or retiming. You can append clips to a timeline and delete them. The space between those two operations — everything that constitutes actual editing — remains entirely manual.

Most of the colour page is inaccessible. Primary wheels, curves, qualifiers, power windows, and OFX effects are all invisible to the API. The node graph cannot be built, modified, or reordered via script. Only CDL values and LUT assignments are writable.

Fairlight is mostly closed. The mixer, EQ, dynamics, bus routing, audio automation, fades, and recording cannot be scripted. Voice isolation state and Fairlight preset application (added in Resolve 20.2.2) are the only meaningful additions.

Smart Bins cannot be created via script. Writing metadata to clips with SetMetadata() populates existing Smart Bins indirectly — but the bins themselves must be created and configured manually.

OFX plugins are invisible to scripts on any page.

AI features and the Python API: an honest assessment

DaVinci Resolve 20 ships with an extensive AI feature set — Magic Mask, Speed Warp, Voice Isolation, Scene Cut Detection, AI IntelliScript, SuperScale, and more. Almost none of these are accessible through the scripting API.

The narrow exceptions: Magic Mask creation can be triggered (not configured). Audio transcription can be triggered (the text is not retrievable via API). Voice isolation state can be queried and toggled. Scene Cut Detection can be called but not parameterised.

Everything else — SuperScale, Dialogue Matcher, AI Audio Assistant, Facial Recognition, generative AI features — cannot be triggered, configured, or monitored via script. Blackmagic has not prioritised exposing Neural Engine functionality to the scripting layer. Resolve 20’s point releases have added targeted capabilities, but the AI feature set remains primarily manual.

Using AI to write Resolve Python scripts

LLMs can generate working Resolve scripts, but with a consistent and predictable failure mode: they invent methods that do not exist. GetSelectedTimelineClips(), SetEffect(), AddTransition() — all plausible, all well-named, all absent from the API.

The mitigation is simple. The Resolve scripting README is roughly 15–20KB — small enough to fit in any modern LLM’s context window. Paste the full documentation as context, instruct the model to use only documented methods, and ask for small focused scripts rather than monolithic solutions. Cross-reference every generated method call against the README before executing.

The davinci-resolve-mcp project (github.com/samuelgursky/davinci-resolve-mcp) takes this further — it implements the Model Context Protocol to connect Claude, Cursor, and VS Code Copilot directly to a running Resolve instance, exposing all 324 API methods as structured tools and preventing hallucination by constraining the AI to verified, documented operations. This is the most complete AI-to-Resolve scripting integration currently available.

Known bugs and version issues in Resolve 20

These appear in production, not just in testing.

fu.GetCurrentComp() returns None unless the Fusion page has been visited at least once in the current session. Opening the Fusion page via script before accessing compositions is the standard workaround.

The first AddRenderJob() call in a new project occasionally fails silently. Adding a short delay or a retry mechanism handles this reliably.

On Windows, Python 3.11+ can cause segfaults with fusionscript.dll. Downgrading to Python 3.10 resolves this.

Environment variable paths on Windows must not contain quotation marks — despite the official documentation’s examples including them.

Blackmagic has broken undocumented API methods without notice. Resolve 18.5 Beta 3 disabled all undocumented functions. Any automation built on undocumented calls should be treated as fragile and tested on every Resolve update.

Resources and ecosystem

Official documentation: The README.txt scripting API document ships with Resolve under Help > Documentation > Developer. It is a plain-text file with no examples and no formatting. The community-maintained formatted version by X-Raym at extremraym.com/cloud/resolve-scripting-doc/ is the de facto standard reference. His GitHub Gist preserves version diffs across releases — essential for tracking what changed in each update.

Community forums: The Blackmagic Design forum scripting section is the best source for troubleshooting and undocumented API discoveries. The We Suck Less forum (steakunderwater.com) has over 225 scripting topics and is where many advanced scripts are shared first.

Python wrapper libraries: pydavinci provides typed wrappers with IDE auto-completion. pybmd on PyPI offers a similar interface. Both make development faster and surface errors before execution rather than during it.

Notable community tools: davinci-resolve-mcp (AI assistant integration), auto-subs (AI subtitle generation with direct Resolve placement), StoryToolkitAI (Whisper-based transcription with semantic footage search), and davinci-resolve-postgresql-workflow-tools (automated PostgreSQL database backup and optimisation).

API maturity: The ecosystem is growing but remains underserved relative to Resolve’s actual feature depth. The official documentation has not changed format since the API was introduced. Coverage of Resolve’s full feature set is approximately 30–40%. Build automation around the API’s proven strengths — delivery, project management, media operations, metadata, and markers — and treat its limitations as fixed constraints rather than temporary gaps.

What this looks like in practice

On a 28-minute broadcast documentary, a complete delivery script handles broadcast MXF, streaming H.265, archive ProRes, and a promo cut — with standardised naming and correct output paths — in a single terminal command. A technical media audit catches frame rate and resolution mismatches before render begins. A QC marker extraction produces a formatted report without manual timecode transcription.

None of these scripts are technically complex. The investment in writing them is recovered within the first project that uses them.

The DaVinci Resolve Python API does not automate everything. It automates the right things: the repetitive, error-prone, administratively heavy operations that surround the creative and technical work. That distinction matters when deciding what to script and what to leave alone.

Poul Waligora is a Senior Colourist and Finishing Supervisor at Wild Lion Media, a documentary post-production studio based in Poland. Wild Lion Media handles full picture finishing pipelines for long-form documentary projects — conform, colour grading, QC, and broadcast delivery — for international productions.