Nix Executor

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:

1. Check the error message for syntax issues
2. Use --show-trace for detailed error traces
3. Validate individual subexpressions
4. 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

1. Start Simple: Test small expressions before complex ones
2. Use --dry-run: Avoid unintended builds during testing
3. Check Syntax First: Use nix-instantiate --parse to validate syntax
4. Use --show-trace: Get detailed error information when debugging
5. Format Output: Use --json with jq for readable structured output
6. Test Incrementally: Break complex expressions into smaller testable parts

Troubleshooting

Common Issues

Infinite Recursion:

# Use --max-call-depth to prevent runaway evaluation
nix eval --max-call-depth 1000 --expr 'EXPRESSION'

Path Not Found:

# Ensure you're in the right directory for relative imports
# Or use absolute paths
nix eval --expr 'import /absolute/path/to/file.nix'

Attribute Missing:

# Check if attribute exists first
nix eval --expr 'builtins.attrNames (import ./file.nix)'

References

• Nix Manual - nix eval
• Nix Manual - nix-instantiate
• Nix Manual - Built-in Functions