Skip to content

Understanding Nuke's '.nk' file structure

March 4, 2025 · 8 min read

Kasimir Malevich, Stroyuschiysya dom [House under construction], 1916

Recently as a small side-project, I attempted to build a next-node prediction model for Nuke—a plugin that would analyze compositing scripts to identify common node patterns and automatically suggest next nodes to add to your scene.

For training, I needed to parse numerous Nuke scripts, flatten any groups or gizmos, and reconstruct their node structures in a PyTorch-compatible format. While I could have launched Nuke for each script and used its Python API to extract the graph structure, it was quite a bit more efficient to directly parse the '.nk' files themselves.

After all, the '.nk' files are human-readable TCL scripts that contain all the structural information I needed. After wrapping my head around the structure and a lot of trial-and-error, I built a lightweight parser that could generate training examples without the overhead of launching any Nuke processes.

If you're looking for an off-the-shelf nuke script parser, take a look at Max Wiklund's implementation here. For those interested in understanding how Nuke scripts work under the hood, let's dive into their structure.


Anatomy of a Nuke File

Header Section

Each .nk file begins with something like this:

#! /path/to/nuke -nx
version 14.0 v5
define_window_layout_xml {<layout>...</layout>}
Root {
 inputs 0
 name /path/to/your/project.nk
 frame 1001
 ...
}

The header section defines:

  1. The Nuke version used to create the file.
  2. Layout information for the Nuke interface.
    • Defines this as an XML representation.
    • Ensures panel configurations, window positions, etc. are consistent when launching the script.
  3. Root node settings (frame-range, resolution, whatever else)
    • If the script is saved as a 'LiveGroup', this will be replaced by a 'LiveGroupInfo' struct.

Node Definitions

After the header, you'll find individual node definitions. Each node is defined with its type followed by curly braces that contain any non-default parameters.

Read {
 inputs 0
 file_type jpeg
 file /path/to/image.jpg
 format "1920 1080 0 0 1920 1080 1 HD"
 origset true
 name Read1
 xpos 180
 ypos -34
}

Key elements to look out for:

  1. Node Class: (e.g. Read, Merge, ColorCorrect)
    • Retrievable via node_instance.Class() in Nuke Python API.
  2. inputs: Defines the number of inputs for the node.
    • Node definitions do not specify outputs.
    • This is handled by the group stack (to be explained below)
    • You may encounter values like: inputs 3+1
      • Indicates 3 regular inputs plus 1 optional input, usually the mask.
      • (Like a Merge node using its B, A, and 'A2' inputs alongside its 'mask' input.)
  3. Node Parameters: Defines other parameters for the node.
    • Not all parameters are explicitly defined in the script!
    • Some parameters might not be defined if they have default values.
      • You can check a knob's default value with: knob.defaultValue()
      • Or for a simpler boolean check: knob.notDefault().
      • To force a knob to always write to disk, use knob.setFlag(nuke.ALWAYS_SAVE)
  4. name: The node's name within the current group.
    • Equivalent to node_instance.name(), not node_instance.fullName()
  5. xpos/ypos: The node's location.

How Node Connections Work

While node definitions specify the number of inputs a node has, they don't explicitly define which nodes connect to these inputs. Instead, connections between nodes are defined by the order in which nodes appear in the '.nk' file.

Nuke maintains a group connection stack, pushing each node onto the stack after processing it.

Connection rules:

  1. Nodes are processed in the order they appear in the file (top to bottom).
  2. When a node is processed, it is pushed onto a connection stack for the current group.
  3. When a subsequent node with inputs > 0 is processed, it pops the most recent N nodes off the stack, where N is the number of inputs.
    • The most recent node connects to input 0, the next to input 1, and so on.
    • On a Merge node, input 0 is B and input 1 is A.

Stacks below are written with the most recent node first.

If it's not making immediate sense, try working through the simple example below:

CheckerBoard1 and Read1 connect to inputs A and B of Merge1
CheckerBoard2 {
 inputs 0
}
Read {
 inputs 0
}
Merge2 {
 inputs 2
}
  1. Start at CheckerBoard2. Stack is [].
    • Nothing is connected. Add CheckerBoard2 to the stack.
  2. Continue to Read. Stack is [CheckerBoard2]
    • Nothing is connected.
    • Leave CheckerBoard2 on the stack and add Read on top.
  3. Continue to Merge2. Stack is [Read, CheckerBoard2]
    • Defines two inputs.
    • Input B (input 0) connects to the most recent node: Read
    • Input A (input 1) connects to the next node: CheckerBoard2
    • Add Merge2 to the stack.
  4. Stack is now [Merge2]

set/push syntax

The basic example above works great for simple scripts! We can easily place nodes onto the stack and then pop them off, building linear chains of nodes all the way down.

But what happens when we want to merge in a separate branch from another part of the node graph? Those nodes have already been added and removed from the stack! The flat-structure described above won't cut it.

This is where the set and push keywords allow Nuke to store previously processed Nodes as variables and push them back onto the stack as needed. This allows the script to "remember" previously processed nodes, connecting them back up as needed.

set

Stores a node from the stack under a variable name, without changing the stack.

set Neb1d4400 [stack 0]

  • set: keyword
  • Neb1d4400: variable name, later referenced with $ prefix.
  • [stack 0]: returns the node at the top of the stack (stack 0) without removing it.
push

Push the node associated with the variable back onto the stack.

push $Neb1d4400

  • push: keyword
  • $Neb1d4400: Looks up the node associated with Neb1d4400 and pushes it back onto the stack.

Let's work through an extended example below:

CheckerBoard1 branches to Grade1 and Merge1; Merge1 and Grade1 connect to Merge2
CheckerBoard2 {
 inputs 0
}
set Neb1d4400 [stack 0]
Grade {
}
push $Neb1d4400
Read {
 inputs 0
}
Merge2 {
 name Merge1
 inputs 2
}
Merge2 {
 name Merge2
 inputs 2
}
  1. Start at CheckerBoard2. Stack is [].
    • Nothing is connected. Add CheckerBoard2 to the stack.
  2. Read the set Neb1d4400 [stack 0] line.
    • Store CheckerBoard2 under the Neb1d4400 variable.
    • Continue parsing, do not alter stack.
  3. Continue to Grade. Stack is [CheckerBoard2]
    • No inputs defined? Safe to assume it takes 1 input from the stack if not explicitly defined.
    • Pop CheckerBoard2 and connect as the only input.
    • Push Grade onto the stack.
  4. Read the push $Neb1d4400 line.
    • Pushes the $Neb1d4400 variable back onto the stack.
    • Remember CheckerBoard2 was stored under this variable on #2.
  5. Continue to Read. Stack is [CheckerBoard2, Grade]
    • Nothing is connected.
    • Push Read onto the stack.
  6. Continue to next node, named Merge1. Stack is [Read, CheckerBoard2, Grade]
    • Defines two inputs.
    • Input B (input 0) connects to the most recent node: Read
    • Input A (input 1) connects to the next node: CheckerBoard2
    • Add Merge1 to the stack.
  7. Continue to next merge, named Merge2. Stack is now [Merge1, Grade]
    • Input B (input 0) connects to the most recent node: Merge1
    • Input A (input 1) connects to the next node: Grade
    • Add Merge2 to the stack.

Note: You may encounter push 0, which is used to push an "empty" connection to the stack.

Read {
 inputs 0
}
# Push an "empty" connection to stack.
push 0

# Stack is [empty, Read]
Merge2 {
  inputs 2
}
# Input B is empty, Input A is the Read node!

Thanks to Nuke's DAG, with a stack and the two main operations (set and push), node connections are captured in relatively simple TCL syntax.

This covers the core of how a Nuke script is wired together! The rest of the post will describe some of the gotchas and tricks when trying to build a script parser.

Group Stacks

Each stack is maintained in relation to its parent group. Each Nuke script begins with a single parent-level group named Root. This is the first Node definition in every script (excluding LiveGroups).

Whenever the script encounters a Group or a localized LiveGroup type, a new group stack will begin. Nuke indents the contents of nested groups, but the indentation is only for readability. A parser should track the Group and end_group lines instead.

When the end_group keyword is encountered, the current group stack is finished.

ColorBars1 flows through Group1 to Viewer1; inside Group1, Input1 flows through ColorCorrect1 to Output1
Root {
}
ColorBars {
 inputs 0
}
# Root stack is set aside. Group1 begins.
Group {
 name Group1
}
 Input {
  inputs 0
 }
 ColorCorrect {
  saturation 2.2
  name ColorCorrect1
 }
 Output {
  name Output1
 }
end_group
# Group 1 ends. Root group resumes.
Viewer {
}
  1. Process Root Node. Begin Root Group.
    • Stack is [] (Root node is never added to stack.)
  2. Continue to ColorBars.
    • Push ColorBars onto the root stack.
  3. Continue to Group. Root stack is [ColorBars].
    • Pop ColorBars and connect it as input.
    • Push Group onto root stack. Root stack is [Group].
    • Begin new stack for Group!
  4. We're now inside Group1. Continue to group's Input node.
    • Push Input onto Group1's stack.
  5. Continue to Group1.ColorCorrect. Group stack is [Input].
    • Pop off Input and connect it.
    • Push Group1.ColorCorrect onto stack.
  6. Continue to Output node.
    • Pop off Group1.ColorCorrect and connect it.
    • Push Output onto stack.
  7. Process end_group line. Indicates that Group1 is finished!
    • Dispose of Group1's stack.
    • Pickup the Root stack and continue.
  8. Continue to Viewer. Root stack is [Group].
    • Pop Group and connect it to the viewer.

Troubleshooting Broken Scripts

Sometimes the Nuke script structure can get corrupted, leading to errors like:

can't read "Nbf7c9d0": no such variable

For a quick fix:

  1. Open up the .nk file.
  2. Search for the variable name, in this case Nbf7c9d0.
  3. You'll find a line like push $Nbf7c9d0.
  4. Delete that line and replace it with a NoOp that has no inputs:
NoOp {
 inputs 0
}

The script should now open up without an error. The problematic node will be replaced with a NoOp, allowing the user to fix the script manually.

This means it's trying to push a node with the variable Nbf7c9d0 onto the stack, but no earlier set command defined that variable. Like the push it replaces, a NoOp with inputs 0 adds exactly one node to the stack, so the order of the stack is maintained. (A plain NoOp {} would take an input off the stack first, shifting every connection after it. Writing push 0 instead also works, leaving an empty input.)

Multi-line Parameters

Not all node parameters are defined on a single line. If you're attempting to implement a Nuke script parser, ensure you track brace depth to properly handle these parameters.

Roto nodes contain their complex data within the node definition and are a likely candidate for expanding the size of your Nuke script files.


That's all! Thanks for reading.