Configuration (.npkillrc)

The .npkillrc file lets you configure npkill's default behavior, create custom profiles, and save your preferences so you don't have to specify them every time.

File Location

npkill looks for the configuration file in this order and uses the first one it finds:

  1. The path given with the --config flag
  2. ./.npkillrc in the current directory
  3. ~/.npkillrc in your home directory
npx npkill --config /path/to/my-config.json

Configuration Options

The .npkillrc file uses JSON format. Here's a complete example:

~/.npkillrc 
{
  "rootDir": "/home/user/projects",
  "exclude": ["important-project", "production-app"],
  "sortBy": "size",
  "sizeUnit": "auto",
  "includeSensitiveResults": false,
  "dryRun": false,
  "defaultProfiles": ["node", "webdev"],
  "profiles": {
    "webdev": {
      "description": "Frontend artifacts and build outputs",
      "targets": ["dist", ".next", ".nuxt", ".output", "build"]
    }
  }
}

Available Options

Option Type Description
rootDir string Absolute path to start searching from. ~ is not expanded
exclude string[] Directories to skip, with the same patterns as -E. They are added to the ones given with -E
sortBy string Default sort order: "none", "size", "path" or "age". Default "none"
sizeUnit string Size display unit: "auto", "mb" or "gb". Default "auto"
includeSensitiveResults boolean Whether to show sensitive results. Default false
dryRun boolean Simulate deletions without deleting anything. Default false
defaultProfiles string[] Profiles to use when you don't pass -p or -t. Built-in or your own, never empty. Default ["node"]
profiles object Custom profile definitions

Custom Profiles

You can define your own profiles in the profiles section. Each profile needs a name, description, and list of targets. A target is a folder name or a rule:

~/.npkillrc 
{
  "profiles": {
    "mystack": {
      "description": "My full-stack development artifacts",
      "targets": [
        "node_modules",
        "dist",
        ".next",
        "__pycache__",
        ".venv",
        "target"
      ]
    }
  }
}

Then use it with:

npx npkill -p mystack
Custom profiles with the same name as built-in profiles will override them. all is reserved.

Priority Order

Options are applied in this order (later options override earlier ones):

  1. .npkillrc file — Default configuration
  2. CLI flags — Command-line arguments
  3. Options panel — Changes made in the TUI options panel (temporary)

This means you can set sensible defaults in your .npkillrc and override them when needed with CLI flags.

Example Configurations

JavaScript Developer

~/.npkillrc 
{
  "defaultProfiles": ["node"],
  "rootDir": "/home/user/dev",
  "sortBy": "size"
}

Full-Stack Developer

~/.npkillrc 
{
  "sortBy": "size",
  "defaultProfiles": ["node", "python"]
}

Game Developer

~/.npkillrc 
{
  "rootDir": "/home/user/GameProjects",
  "defaultProfiles": ["unity", "unreal", "godot"]
}

Validation

npkill checks the file every time it starts: unknown properties, types and values. If something is wrong, it shows a configuration error with the reason and exits without scanning. A missing ~/.npkillrc is fine, but a file passed with --config must exist.