[!NOTE] Documentation is auto-generated with claude-3.7, may not be current or accurate and is subject to change.

nk2dl Configuration

The nk2dl package uses a multi-level configuration system that allows for flexible settings at different levels of scope.

Configuration Hierarchy

Configuration values are loaded and overridden in the following order (later sources override earlier ones):

Default configuration - Baseline values built into the package
Project configuration - config.yaml in the nk2dl module directory
Environment variables - NK2DL_* variables
User configuration - ~/.nuke/nk2dl/config.yaml in the user’s .nuke directory

Configuration File Format

Configuration files use YAML format:

deadline:
  use_web_service: true
  host: deadline-server
  port: 8081
  ssl: false
  commandline_on_fail: true

logging:
  level: INFO
  file: null
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

submission:
  pool: nuke
  group: none
  priority: 50
  chunk_size: 10
  department: comp
  batch_name_template: "{script_stem}"
  job_name_template: "{batch} / {write} / {file}"

Available Configuration Sections

Deadline Connection

deadline:
  # Whether to use Deadline Web Service (vs command line)
  use_web_service: true
  
  # Deadline Web Service host
  host: deadline-server
  
  # Deadline Web Service port
  port: 8081
  
  # Whether to use SSL for the web service connection
  ssl: false
  
  # Path to SSL certificate file (required if ssl is true)
  ssl_cert: null
  
  # Fall back to command line if web service fails
  commandline_on_fail: true

Logging

logging:
  # Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  level: INFO
  
  # Log file path (null for no file logging)
  file: null
  
  # Log format
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
  
  # Level for Qt debug messages (default: DEBUG)
  # Set to WARNING or higher to disable Qt debugging
  qt_level: DEBUG
  
  # Level for caller information in debug messages (default: DEBUG) 
  # Only shows caller info when main logging level is at or below this level
  call_level: DEBUG

Advanced Logging Levels

The logging system uses standard Python logging levels:

CRITICAL (50): Critical errors only
ERROR (40): Error messages and above
WARNING (30): Warning messages and above
INFO (20): Informational messages and above
DEBUG (10): All debug messages
NOTSET (0): All messages

To enable Qt debugging with caller info:

logging:
  level: DEBUG          # Enable all debug messages  
  qt_level: DEBUG       # Enable Qt debugging
  call_level: DEBUG     # Show caller info for debug messages

To disable Qt debugging but keep other debug messages:

logging:
  level: DEBUG          # Enable debug messages
  qt_level: WARNING     # Only show Qt warnings/errors
  call_level: DEBUG     # Normal caller info threshold

Job Submission

submission:
  # Deadline pool
  pool: nuke
  
  # Deadline group
  group: none
  
  # Job priority (0-100)
  priority: 50
  
  # Frame chunk size
  chunk_size: 10
  
  # Department name
  department: comp
  
  # Template for batch names
  batch_name_template: "{script_stem}"
  
  # Template for job names
  job_name_template: "{batch} / {write} / {file}"
  
  # Action to take when job completes ("Nothing", "Archive", "Delete")
  on_job_complete: null
  
  # Whether to submit jobs in suspended state
  submit_suspended: false
  
  # Comma-separated list of limit names that this job must obey
  limit_groups: null
  
  # Task timeout in seconds (0 for no timeout)
  task_timeout: null
  
  # Whether to enable automatic task timeout
  enable_auto_timeout: false
  
  # Whether to limit tasks to worker's task limit
  limit_worker_tasks: false
  
  # Whether to submit write nodes as separate jobs
  write_nodes_as_separate_jobs: false
  
  # Whether to submit write nodes as tasks
  write_nodes_as_tasks: false
  
  # Whether to create dependencies based on render order
  render_order_dependencies: false
  
  # Default number of render threads
  render_threads: 0
  
  # Whether to use GPU by default
  use_gpu: false
  
  # Whether to use NukeX by default
  use_nuke_x: false
  
  # Whether to use Nuke Studio by default
  use_nuke_studio: false
  
  # Script copying options
  copy_script: false
  submit_copied_script: false
  
  # Script copy path with full path template (directory + filename) and tokens available:
  # Script directory tokens: {nkdir}, {scriptdir}, {nukescriptdir}
  # Script stem tokens: {nkstem}, {scriptstem}, {nukescriptstem}
  # Script name tokens: {nk}, {script}, {scriptname}, {nukescript}
  # Output directory tokens: {outdir}, {outputdir}
  # Output stem tokens: {filestem}, {filenamestem}, {outstem}, {outputstem}
  # Output tokens: {output}
  # Extension token: {ext}
  # Date/time tokens: {YYYY}, {YY}, {MM}, {DD}, {hh}, {mm}, {ss}
  # Temp directory tokens: {tmp}, {temp}, {tmpdir}, {tempdir}
  # UUID token: {uuid}
  script_copy_path: "{outdir}/.farm/{nkstem}.nk"
  
  # Multiple copy locations (optional)
  # script_copy0_path: "{outdir}/.farm/{nukescript}"  # First copy with output directory token
  # script_copy1_path: "{nkdir}/archive/{nkstem}_{YYYY}-{MM}-{DD}.nk"  # Second copy with script directory token
  
  # Build job options
  # Whether to automatically delete the build job script after execution
  delete_build_job_script: true
  
  # Build job script path with tokens available:
  # Script directory tokens: {sdir}, {nkdir}, {scriptdir}, {nukescriptdir}
  # Script stem tokens: {ss}, {basename}, {stem}, {sstem}, {scriptstem}
  # Script name tokens: {s}, {script}, {scriptname}
  # Date tokens: {YYYY}, {YY}, {MM}, {DD}, {hh}, {mm}, {ss}
  # Example: "{scriptdir}/build_jobs/{stem}_{YYYY}-{MM}-{DD}.py"
  build_job_script_path: null  # Full path template for both directory and filename
  
  # Environment variables
  use_current_environment: false     # Use current environment variables
  environment_keys: []              # List of environment variables to include (if not using all)
  environment: {}                    # Add or override environment variables
  omit_environment_keys: []          # Environment variables to omit
  
  # Machine list options
  machine_allow_list: null          # List of machines allowed to render this job
  machine_deny_list: null           # List of machines not allowed to render this job

Nuke Settings

nuke:
  # Default version to use (null for auto-detect)
  version: null
  
  # Path to Nuke executable (null for auto-detect)
  executable: null

Environment Variables

All configuration settings can be overridden with environment variables using the format NK2DL_SECTION_KEY:

# Windows PowerShell
$env:NK2DL_DEADLINE_USE__WEB__SERVICE = "True"
$env:NK2DL_DEADLINE_HOST = "deadline-server"
$env:NK2DL_SUBMISSION_PRIORITY = "75"
$env:NK2DL_LOGGING_LEVEL = "DEBUG"

# Linux/macOS
export NK2DL_DEADLINE_USE__WEB__SERVICE=True
export NK2DL_DEADLINE_HOST=deadline-server
export NK2DL_SUBMISSION_PRIORITY=75
export NK2DL_LOGGING_LEVEL=DEBUG

Note that:

Section and key are separated by single underscores (_)
For keys containing underscores, use double underscores (__) in the environment variable
Boolean values should be True or False (case-sensitive)

Examples:

deadline.use_web_service → NK2DL_DEADLINE_USE__WEB__SERVICE
submission.chunk_size → NK2DL_SUBMISSION_CHUNK__SIZE

Why Double Underscores?

The double underscore convention is necessary because environment variables use underscores to separate the prefix (NK2DL), section (DEADLINE), and key name. Since some configuration keys also contain underscores (like use_web_service), we need a way to distinguish between:

The underscores that separate parts of the environment variable name
The underscores that are part of the original configuration key

By replacing underscores in configuration keys with double underscores in environment variables, the configuration system can correctly parse the variable names back into their proper configuration paths. When processed, the double underscores are converted back to single underscores.

Project Configuration

The master configuration file is located at nk2dl/config.yaml in the module directory. This is the default configuration used for all projects.

You can override this configuration by setting the NK2DL_CONFIG environment variable to point to a custom configuration file:

# Windows
set NK2DL_CONFIG=C:\path\to\your\custom_config.yaml

# PowerShell
$env:NK2DL_CONFIG = "C:\path\to\your\custom_config.yaml"

# Linux/macOS
export NK2DL_CONFIG=/path/to/your/custom_config.yaml

User Configuration

Create a config.yaml file in ~/.nk2dl/ to set user-specific defaults:

deadline:
  host: my-deadline-server
  port: 8081

logging:
  level: INFO
  file: "~/nk2dl_logs/nk2dl.log"

Templating

Templates for batch and job names support the following variables:

Variable	Description
`{script}`	Script name with extension
`{script_stem}`	Script name without extension
`{write}`	Write node name
`{file}`