Q100475: How to isolate issues with the .nuke directory



This article covers how to troubleshoot the .nuke directory and isolate which customisations could be causing issues with Nuke.


Nuke can be greatly customised by adding plug-ins, gizmos or other customisations. However, as many of these customisations are written in isolation, they can cause Nuke to behave incorrectly, or even crash.

If Nuke is demonstrating incorrect behaviour or crashing, then the first thing to check is if the issues are caused by customisations.

The best way to do this is by launching Nuke in safe mode, as this disables all plug-ins, gizmos and other customisations, with the exception of environment variables. Information about how to launch Nuke in safe mode can be found in the following article:

Q100038: Launching Nuke/NukeX/NukeStudio/Hiero in safe mode

If after testing in safe mode the problem no longer occurs, then the issue is probably due to a customisation added to Nuke, adversely affecting Nuke’s behaviour.

Such customisations can be added to a number of locations, which are listed in the Nuke documentation below:

Loading Gizmos, NDK Plug-ins, and Python and Tcl Scripts

To further isolate which customisation or combination of customisations is causing the problem, we recommend launching Nuke in verbose mode and following the steps in this article:

Q100112: Launching Nuke in verbose mode and isolating potential customisations causing issues

While troubleshooting, if removing the .nuke folder resolves the issue, then the next step is to isolate the culprit customisations within the .nuke directory.

NOTE: The verbose Nuke log may display errors related to certain customisation files that may help narrow down the area of investigation.


The most common place to add customisations, like scripts or gizmos, is the .nuke directory located in the user's home directory. The default locations of the user .nuke directory are listed below:

Windows: C:\Users\<username>\.nuke

Linux: /home/<username>/.nuke

macOS: /Users/<username>/.nuke

NOTE: Please be aware that on some operating systems, the .nuke directory may be hidden. If this is the case, then please check the operating system’s documentation on how to show hidden directories and access the .nuke directory.



The easiest way to check if one of the customisations in the .nuke directory is causing the issue, is to rename the .nuke directory to something like old.nuke. The next time Nuke launches, it will create a fresh .nuke directory. If the issue no longer occurs, then it indicates that something in the original .nuke directory was causing the issue.

At this point the user’s home directory should contain:

     old.nuke - the original customisations

     .nuke - default directory created during the last Nuke launch

Inside the old.nuke directory, to isolate exactly what was causing the issue, a good method to use is split-half troubleshooting. The idea behind it is to continually split the files to be tested in half and test each part to see if the issue is still reproducible, until the culprit is identified.

NOTE: Before following this method make sure no other plug-ins, gizmos or customisations are available on your machine apart from the ones inside the user’s .nuke directory.

Split-half troubleshooting method:

  1. Go to the old.nuke folder and copy half of the customisation files into the fresh .nuke directory created by Nuke.
  2. Relaunch Nuke and check if the issue still occurs.
  3. If the issue persists then go to the .nuke directory and remove half of the files. Relaunch Nuke and see if the issue continues to happen. Repeat this step while the issue persists until only a single file is left in your .nuke folder. At this point you have identified the culprit customisation.
  4. If the issue no longer occurs after copying half of the old.nuke directory into the fresh .nuke, then remove the contents of the .nuke directory and copy the other half you haven’t tested from inside the old.nuke directory and repeat step 3.
  5. If the issue doesn’t occur after copying and testing either half of the old.nuke directory content, this indicates that a combination of customisations are affecting the setup. In this case recopy the entire old.nuke directory content into the fresh .nuke, then remove one customisation file at a time, launch Nuke and test if the issue still occurs until the smallest set of files that trigger the issue are identified.

Once a single customisation file or the smallest set of files that recreate the issue have been isolated, these files can then be troubleshot further. Using the same split-half troubleshooting method, lines of code can be removed until the relevant section is identified within the file or files.

Depending on the customisation type, files like TCL or Python scripts can be opened in a text editor and tested further, other files like compiled NDK plugins may not be editable, so the creator of the plug-in will need to be contacted.

    We're sorry to hear that

    Please tell us why