nushell-plugins/guides/REGISTER_CORE_PLUGINS.md

Registering Nushell Core Plugins

Version: 1.0.0 Updated: 2025-10-22 Nushell: 0.108.0+

Overview

Nushell core plugins are built-in plugins that come with Nushell when you build it with the --workspace flag. They provide essential functionality like data analysis, format conversion, Git integration, and more.

Core plugins include:

• nu_plugin_polars - Data analysis with Polars
• nu_plugin_formats - Format conversion
• nu_plugin_inc - Increment operations
• nu_plugin_gstat - Git status information
• nu_plugin_query - Advanced querying
• nu_plugin_custom_values - Custom value handling
• nu_plugin_example - Example plugin template
• nu_plugin_stress_internals - Stress testing

---

How Plugin Registration Works

When you register a plugin, you're telling Nushell where to find the plugin binary and to load it automatically. This happens by:

1. Registering: nu -c "plugin add /path/to/nu_plugin_*"

   • Adds plugin path to Nushell config
   • Plugin loads on next Nushell startup

2. Listing: nu -c "plugin list"

   • Shows all registered plugins
   • Verifies registration worked

3. Removing: nu -c "plugin rm plugin_name"

   • Removes plugin from config
   • Plugin unloads after restart

---

Method 1: Manual Registration

Register a Single Core Plugin

# After building nushell with --workspace
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_polars"

Replace the path with your actual Nushell target directory.

Register Multiple Core Plugins

# Register all built plugins
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_polars"
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_formats"
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_inc"
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_gstat"
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_query"
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_custom_values"

Verify Registration

nu -c "plugin list"

Expected output shows all registered plugins with their versions.

---

Method 2: Script-Based Registration

Using the Installation Script

If plugins are in ~/.local/bin/:

./install_from_manifest.nu --all --register-only

This registers all plugins from the manifest.

Using a Custom Nushell Script

Create a file register_core_plugins.nu:

#!/usr/bin/env nu

# Register Nushell core plugins
def register_core_plugins [plugin_dir: string] {
    let core_plugins = [
        "nu_plugin_polars"
        "nu_plugin_formats"
        "nu_plugin_inc"
        "nu_plugin_gstat"
        "nu_plugin_query"
        "nu_plugin_custom_values"
    ]

    for plugin in $core_plugins {
        let plugin_path = $"($plugin_dir)/($plugin)"

        if ($plugin_path | path exists) {
            try {
                # Remove old registration if exists
                nu -c $"plugin rm ($plugin | str replace '^nu_plugin_' '')" out+err>| null
            } catch {}

            # Register new
            nu -c $"plugin add ($plugin_path)"
            print $"✓ Registered: ($plugin)"
        } else {
            print $"✗ Not found: ($plugin_path)"
        }
    }
}

# Main
let plugin_dir = if ($env | get -i NUSHELL_PLUGIN_DIR) != null {
    $env.NUSHELL_PLUGIN_DIR
} else {
    "/path/to/nushell/target/release"
}

register_core_plugins $plugin_dir

Run it:

chmod +x register_core_plugins.nu
./register_core_plugins.nu

---

Method 3: After Building Nushell

Step-by-Step After cargo build --workspace

1. Build Nushell with workspace (includes core plugins):

cd nushell
cargo build --release --workspace

2. Find where core plugins were built:

ls nushell/target/release/nu_plugin_*

3. Copy to installation directory (optional, for easy access):

cp nushell/target/release/nu_plugin_* ~/.local/bin/

4. Register plugins:

# Option A: Register from build directory
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_polars"
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_formats"
# ... repeat for all core plugins

# Option B: Register from ~/.local/bin/
nu -c "plugin add ~/.local/bin/nu_plugin_polars"
nu -c "plugin add ~/.local/bin/nu_plugin_formats"
# ... repeat for all core plugins

5. Verify:

nu -c "plugin list"

---

Method 4: Bulk Registration Script

Create register_all_core_plugins.sh

#!/bin/bash

# Nushell core plugins registration script
# Usage: ./register_all_core_plugins.sh /path/to/nushell/target/release

PLUGIN_DIR="${1:-.}"

if [ ! -d "$PLUGIN_DIR" ]; then
    echo "Error: Plugin directory not found: $PLUGIN_DIR"
    exit 1
fi

PLUGINS=(
    "nu_plugin_polars"
    "nu_plugin_formats"
    "nu_plugin_inc"
    "nu_plugin_gstat"
    "nu_plugin_query"
    "nu_plugin_custom_values"
)

echo "Registering Nushell core plugins from: $PLUGIN_DIR"
echo ""

for plugin in "${PLUGINS[@]}"; do
    plugin_path="$PLUGIN_DIR/$plugin"

    if [ -f "$plugin_path" ]; then
        echo "Registering: $plugin"

        # Remove old registration
        nu -c "plugin rm ${plugin#nu_plugin_}" 2>/dev/null || true

        # Register new
        nu -c "plugin add $plugin_path"

        if [ $? -eq 0 ]; then
            echo "✓ Success: $plugin"
        else
            echo "✗ Failed: $plugin"
        fi
    else
        echo "✗ Not found: $plugin_path"
    fi
done

echo ""
echo "Registration complete!"
echo ""
echo "Verify with: nu -c \"plugin list\""

Run it:

chmod +x register_all_core_plugins.sh
./register_all_core_plugins.sh /path/to/nushell/target/release

---

Finding Core Plugins

After Building with --workspace

Core plugins are built in the same directory as the nu binary:

# Find where they're built
find nushell/target/release -name "nu_plugin_*" -type f

# List them
ls -lh nushell/target/release/nu_plugin_*

Checking Installed Plugins

# See what's currently registered
nu -c "plugin list"

# Get detailed info
nu -c "plugin list | each { |it| {name: $it.name, version: $it.version, path: $it.path} }"

---

Troubleshooting

Problem: "Plugin not found"

Cause: Plugin binary doesn't exist at specified path

Solution:

1. Verify you built with --workspace: cargo build --release --workspace
2. Check plugin exists: ls nushell/target/release/nu_plugin_*
3. Use correct full path: nu -c "plugin add /full/path/to/nu_plugin_name"

Problem: "Plugin already registered"

Solution: Remove old registration first:

nu -c "plugin rm polars"  # Remove by short name

Then register new path:

nu -c "plugin add /path/to/nu_plugin_polars"

Problem: Plugin not loading after registration

Solution:

1. Restart Nushell: exit && nu
2. Check registration: nu -c "plugin list"
3. Verify plugin path exists: ls -l /path/to/plugin
4. Check permissions: chmod +x /path/to/nu_plugin_*

Problem: Multiple versions of same plugin

Solution: Remove old versions before registering new:

# Remove
nu -c "plugin rm polars"

# Verify removed
nu -c "plugin list"

# Register new path
nu -c "plugin add /new/path/to/nu_plugin_polars"

---

Common Registration Scenarios

Scenario 1: Fresh Nushell Build

# 1. Build with workspace
cd ~/nushell
cargo build --release --workspace

# 2. Register all core plugins
for plugin in ~/nushell/target/release/nu_plugin_*; do
    nu -c "plugin add $plugin"
done

# 3. Verify
nu -c "plugin list"

Scenario 2: Multiple Nushell Versions

# Register from specific version
nu -c "plugin add /opt/nushell-0.108.0/nu_plugin_polars"

Each Nushell version can have different plugins.

Scenario 3: Distribution Installation

# If plugins are in distribution
./install_from_manifest.nu --all --register-only

# Or manually
nu -c "plugin add ./bin/nu_plugin_polars"
nu -c "plugin add ./bin/nu_plugin_formats"

Scenario 4: Development Workflow

# After each build during development
cargo build --release --workspace -p nu_plugin_polars

# Re-register
nu -c "plugin rm polars"
nu -c "plugin add ./target/release/nu_plugin_polars"

# Test in new shell
exit && nu

---

Plugin Configuration

Where Registration Happens

Plugins are registered in:

~/.config/nushell/env.nu

Each registration adds a line like:

plugin add /path/to/nu_plugin_polars

Manual Configuration

If needed, you can manually edit env.nu:

$EDITOR ~/.config/nushell/env.nu

# Add:
plugin add /path/to/nu_plugin_polars
plugin add /path/to/nu_plugin_formats

Then restart Nushell.

---

Best Practices

✅ DO:

• Use absolute paths: /full/path/to/nu_plugin_name
• Remove old registration before re-registering
• Verify plugins exist before registering
• Check permissions: chmod +x /path/to/plugin
• Test after registration: exit && nu
• Use consistent plugin directory (e.g., ~/.local/bin/)

❌ DON'T:

• Use relative paths (they may not work after shell restart)
• Register plugins that don't exist
• Register without absolute paths
• Forget to restart shell after registration
• Keep multiple copies of same plugin in different locations

---

Quick Reference

Task	Command
Register single	nu -c "plugin add /path/to/nu_plugin_name"
Register all	Use loop or script (see above)
List all	nu -c "plugin list"
Remove	nu -c "plugin rm plugin_name"
Verify	nu -c "plugin list" or restart shell
Check path	nu -c "plugin list | get path"

---

Related Documentation

• Nushell Official: https://www.nushell.sh/book/plugins.html
• Distribution System: See DISTRIBUTION_SYSTEM.md
• Installation: See INSTALLATION_QUICK_START.md
• Full Workflow: See DISTRIBUTION_INSTALLER_WORKFLOW.md

---

Summary

To register Nushell core plugins:

1. Build with workspace: cargo build --release --workspace
2. Register each plugin: nu -c "plugin add /path/to/nu_plugin_name"
3. Verify: nu -c "plugin list"
4. Restart: exit && nu

That's it! Core plugins work exactly like external plugins - just plugin add with the full path to the binary.