Skip to main content
Nuclei supports a configuration file that allows you to customize default settings, template locations, and other preferences. This file provides a persistent way to configure Nuclei without passing command-line flags every time.

​
Configuration file location

Nuclei’s configuration file is located at: 
~/.config/nuclei/config.yaml
The file is automatically created when you first run Nuclei with the -update-templates flag or when you modify any configuration settings.

​
Configuration file format

The configuration file uses YAML format. Here’s a complete example with all available options: 
# Nuclei Templates Directory
nuclei-templates-directory: /path/to/nuclei-templates

# Custom Template Directories
custom-s3-templates-directory: /path/to/s3-templates
custom-github-templates-directory: /path/to/github-templates
custom-gitlab-templates-directory: /path/to/gitlab-templates
custom-azure-templates-directory: /path/to/azure-templates

# Template Version Information
nuclei-templates-version: v9.7.0
nuclei-ignore-hash: abc123def456

# Latest Version Cache (automatically managed)
nuclei-latest-version: v3.1.0
nuclei-templates-latest-version: v9.7.0
nuclei-latest-ignore-hash: xyz789

​
Configuration options

​
Template directories

​
nuclei-templates-directory
string
Path to the main Nuclei templates directory. Defaults to ~/.config/nuclei-templates/.
​
custom-s3-templates-directory
string
Path to custom templates stored in AWS S3.
​
custom-github-templates-directory
string
Path to custom templates from GitHub repositories.
​
custom-gitlab-templates-directory
string
Path to custom templates from GitLab repositories.
​
custom-azure-templates-directory
string
Path to custom templates stored in Azure Blob Storage.

​
Version tracking

​
nuclei-templates-version
string
Currently installed version of Nuclei templates. Automatically updated when templates are installed or updated.
​
nuclei-ignore-hash
string
Hash of the .nuclei-ignore file. Used to detect when the ignore file has been updated.
​
nuclei-latest-version
string
Latest available version of Nuclei (cached from version check).
​
nuclei-templates-latest-version
string
Latest available version of Nuclei templates (cached from version check).

​
Creating a custom configuration

1

Create the config directory

mkdir -p ~/.config/nuclei
2

Create the configuration file

cat > ~/.config/nuclei/config.yaml <<EOF
nuclei-templates-directory: /custom/path/to/templates
EOF
3

Verify the configuration

Run Nuclei and check that it uses your custom configuration:
nuclei -version

​
Using custom template directories

You can configure multiple custom template directories for different sources: 
# Main templates
nuclei-templates-directory: ~/.config/nuclei-templates

# Organization-specific templates
custom-github-templates-directory: ~/.config/nuclei-templates/custom-github

# Private templates from S3
custom-s3-templates-directory: ~/.config/nuclei-templates/custom-s3
When scanning, Nuclei will search all configured directories for templates.
Custom template directories are relative to the main templates directory unless you specify an absolute path.

​
Disabling automatic updates

Use the -duc (disable-update-check) flag to prevent Nuclei from checking for updates: 
nuclei -target example.com -duc
This is useful in air-gapped environments or when you want to control update timing manually.

​
Configuration file precedence

Configuration values are applied in this order (later values override earlier ones):
  1. Default values from pkg/catalog/config/nucleiconfig.go
  2. Configuration file (~/.config/nuclei/config.yaml)
  3. Environment variables
  4. Command-line flags
Command-line flags always take precedence over configuration file settings.

​
Template ignore file

Nuclei also uses a .nuclei-ignore file in the templates directory to exclude specific templates from execution: 
# Location
~/.config/nuclei-templates/.nuclei-ignore

# Format: one template path per line
templates/misconfiguration/example-check.yaml
templates/cves/old-cve.yaml

​
Resetting configuration

To reset Nuclei configuration and templates to defaults: 
nuclei -reset
This command removes all Nuclei configuration files and templates. You’ll need to re-download templates after running this command.

​
Troubleshooting

Nuclei creates the configuration file automatically. If it’s missing:
  1. Run nuclei -update-templates to initialize configuration
  2. Manually create ~/.config/nuclei/config.yaml
  3. Check file permissions on the .config directory
Ensure:
  1. The directory path is absolute or correctly relative
  2. The directory contains valid .yaml template files
  3. File permissions allow Nuclei to read the directory
  4. Use -v flag to see which templates are being loaded
Remember:
  1. Command-line flags override configuration file settings
  2. Environment variables override configuration file settings
  3. Restart any long-running Nuclei processes after config changes
  4. Check for YAML syntax errors in the config file

​
Next steps

Environment variables

Configure Nuclei using environment variables

Template selection

Learn how to select and filter templates

Build docs developers (and LLMs) love

Get started for freeTalk to us