| name | nix-executor |
| description | Use when you need to test Nix expressions, validate Nix configuration syntax before applying, debug Nix code or understand evaluation results, inspect derivation attributes, or evaluate flake outputs and inputs |
| license | MIT |
Nix Code Executor
This skill provides safe execution and evaluation of Nix code, including expressions, derivations, and configuration validation.
What This Skill Does
This skill helps you:
- Evaluate Nix expressions and see their results
- Test Nix derivations before building
- Validate Nix configuration syntax
- Debug Nix code issues
- Inspect Nix store paths and attributes
When to Use This Skill
Use this skill when you need to:
- Test a Nix expression to see what it evaluates to
- Validate Nix configuration syntax before applying
- Debug Nix code or understand evaluation results
- Inspect derivation attributes
- Evaluate flake outputs or inputs
Instructions
When this skill is activated, follow these steps:
1. Determine the Execution Type
Identify what kind of Nix operation is needed:
- Expression evaluation: Use
nix eval for simple expressions
- Instantiation: Use
nix-instantiate to build derivations
- Flake evaluation: Use
nix eval with flake references
- Build testing: Use
nix build --dry-run for dry runs
- Configuration check: Use
nix-instantiate --eval for config validation
2. Choose the Appropriate Command
For simple expressions:
nix eval --expr 'EXPRESSION'
For file-based expressions:
nix-instantiate --eval FILE.nix
For flake outputs:
nix eval .#OUTPUT_PATH
For pretty JSON output:
nix eval --json --expr 'EXPRESSION' | jq
For dry-run builds:
nix build --dry-run .#PACKAGE
For checking derivation attributes:
nix derivation show .#PACKAGE
3. Safety Considerations
- Use
--dry-run when you don't want to actually build anything
- Use
--read-only flag when evaluating untrusted code
- Wrap expressions in
--expr to avoid file system modifications
- Check for evaluation errors before proceeding with builds
4. Common Use Cases
Evaluate a simple expression:
nix eval --expr '1 + 1'
nix eval --expr 'builtins.toString (map (x: x * 2) [1 2 3])'
Check flake configuration:
nix eval .#nixosConfigurations.HOSTNAME.config.system.build.toplevel
Test attribute existence:
nix eval --expr 'builtins.hasAttr "attr" { attr = 1; }'
Inspect package metadata:
nix eval --json nixpkgs#package.meta | jq
Validate Nix file syntax:
nix-instantiate --parse FILE.nix
5. Error Handling
When evaluation fails:
- Check the error message for syntax issues
- Use
--show-trace for detailed error traces
- Validate individual subexpressions
- Check for infinite recursion with
--max-call-depth
Example with trace:
nix eval --show-trace --expr 'EXPRESSION'
6. Output Formatting
Control output format based on needs:
- Default: Nix expression format
--json: JSON format (parseable)--raw: Raw output without quotes--apply: Transform output with a function
7. Working with Files
Evaluate specific attributes:
nix-instantiate --eval --strict --attr attrPath file.nix
Import and evaluate:
nix eval --expr 'import ./file.nix'
Examples
Example 1: Test a Nix Expression
nix eval --expr 'let pkgs = import <nixpkgs> {}; in pkgs.lib.version'
Example 2: Validate Flake Output
nix eval .#darwinConfigurations.MacBook-Pro-Maxim.system
Example 3: Debug Configuration Value
nix eval --json .#nixosConfigurations.hostname.config.services.openssh.enable
Example 4: Check Package Availability
nix eval --expr 'builtins.hasAttr "opencode" (import <nixpkgs> {})'
Example 5: Inspect Derivation
nix derivation show nixpkgs#hello
Best Practices
- Start Simple: Test small expressions before complex ones
- Use --dry-run: Avoid unintended builds during testing
- Check Syntax First: Use
nix-instantiate --parse to validate syntax
- Use --show-trace: Get detailed error information when debugging
- Format Output: Use
--json with jq for readable structured output
- Test Incrementally: Break complex expressions into smaller testable parts
Troubleshooting
Common Issues
Infinite Recursion:
nix eval --max-call-depth 1000 --expr 'EXPRESSION'
Path Not Found:
nix eval --expr 'import /absolute/path/to/file.nix'
Attribute Missing:
nix eval --expr 'builtins.attrNames (import ./file.nix)'
References
