Codakey
Play
← Back to nushell/nushell

How to Deploy & Use nushell/nushell

Nushell Deployment & Usage Guide

Prerequisites

Before installing or building Nushell, ensure you have the following:

Required:

  • Rust toolchain (latest stable version): Install via rustup
  • Git: For cloning the repository
  • C compiler:
    • Linux: gcc or clang (install build-essential on Ubuntu/Debian)
    • macOS: Xcode Command Line Tools (xcode-select --install)
    • Windows: MSVC (Visual Studio Build Tools) or MinGW

Linux-specific dependencies:

  • OpenSSL development libraries (libssl-dev on Debian/Ubuntu, openssl-devel on RHEL/Fedora)
  • pkg-config

Optional (for additional features):

  • Dataframes: Requires additional dependencies for the --features dataframe build
  • Plugins: Rust toolchain for building plugins

Installation

Option 1: Package Manager (Recommended)

macOS and Linux:

brew install nushell

Windows:

winget install nushell

Cargo (cross-platform):

cargo install nu

Other platforms: See the Repology package list for distribution-specific commands.

Option 2: Pre-built Binaries

Download pre-built binaries from the GitHub Releases page or use the nightly builds available via GitHub Actions.

Option 3: Build from Source

# Clone the repository
git clone https://github.com/nushell/nushell.git
cd nushell

# Build release binary (optimized)
cargo build --release

# The binary will be at:
# ./target/release/nu

Build with all features:

cargo build --release --features extra

Build with dataframe support:

cargo build --release --features dataframe

Configuration

Nushell uses two main configuration files:

  • config.nu: Main configuration (keybindings, completions, display settings)
  • env.nu: Environment variables and PATH setup

Locate Config Files

Start Nushell and run:

$nu.config-path
$nu.env-path

Default Configurations

Default configuration templates are located in the repository at:

crates/nu-utils/src/default_files/

Copy these to your config directory or let Nushell generate them on first run.

Key Configuration Options

Table Display Modes (from src/command.rs): Valid values for table_mode: basic, thin, light, compact, with_love, compact_double, default, rounded, reinforced, heavy, none, psql, markdown, dots, restructured, ascii_rounded, basic_compact, single, double

Example config.nu:

# Set table display style
$env.config = {
    table: {
        mode: rounded
        index_mode: always
    }
    completions: {
        case_sensitive: false
        quick: true
    }
}

Error Styles: fancy, plain, short

Environment Setup

Add to env.nu:

# Add custom paths
$env.PATH = ($env.PATH | split row (char esep) | prepend '/usr/local/bin')

# Set editor
$env.EDITOR = "vim"

Build & Run

Development Build

# Quick build for development (slower runtime, faster compile)
cargo build

# Run the development build
cargo run

Production Build

# Optimized release build (recommended for daily use)
cargo build --release

# Run with arguments
cargo run --release -- --help

Running Tests

# Run the test suite
cargo test

# Run tests for a specific crate
cargo test -p nu-command

Feature Flags

Available features (check Cargo.toml for current options):

  • extra: Additional commands
  • dataframe: Dataframe support (requires polars)
  • os: OS-specific features (enabled by default on supported platforms)

Example:

cargo build --release --features extra,dataframe

Deployment

Setting as Default Shell

Linux/macOS:

# Add to /etc/shells (requires sudo)
echo $(which nu) | sudo tee -a /etc/shells

# Change default shell
chsh -s $(which nu)

Windows: Set as default terminal profile in Windows Terminal settings, or set the ComSpec environment variable (advanced).

GitHub Actions

Use the official setup-nu action:

- uses: hustcer/setup-nu@v3
  with:
    version: "0.100.0"
- run: nu --version

Container Deployment

Create a Dockerfile:

FROM rust:latest as builder
WORKDIR /app
RUN git clone https://github.com/nushell/nushell.git
WORKDIR /app/nushell
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y libssl3 ca-certificates
COPY --from=builder /app/nushell/target/release/nu /usr/local/bin/nu
ENTRYPOINT ["/usr/local/bin/nu"]

Distribution

Create distributable archive:

cargo build --release
tar czvf nushell-$(uname -s)-$(uname -m).tar.gz -C target/release nu

Homebrew Formula (for custom taps):

class Nushell < Formula
  desc "A new type of shell"
  homepage "https://www.nushell.sh"
  url "https://github.com/nushell/nushell/archive/refs/tags/0.100.0.tar.gz"
  license "MIT"
  
  depends_on "rust" => :build
  depends_on "openssl@3"
  
  def install
    system "cargo", "build", "--release", "--features", "extra"
    bin.install "target/release/nu"
  end
end

Troubleshooting

Build Issues

Error: openssl-sys crate fails to build

  • Linux: Install libssl-dev and pkg-config
  • macOS: brew install openssl and set OPENSSL_ROOT_DIR or PKG_CONFIG_PATH
  • Windows: Install OpenSSL via vcpkg or use the vendored-openssl feature

Error: "linker cc not found"

  • Install build essentials: sudo apt-get install build-essential (Debian/Ubuntu) or equivalent for your distro

Long compile times

  • Use cargo build --release only for final binaries; use cargo check for development
  • Enable incremental compilation: CARGO_INCREMENTAL=1
  • Use sccache for caching: RUSTC_WRAPPER=sccache cargo build

Runtime Issues

Nushell not found after cargo install

  • Ensure ~/.cargo/bin is in your PATH: $env.PATH = ($env.PATH | split row (char esep) | prepend '~/.cargo/bin')

Config file errors on startup

  • Reset to defaults by removing or renaming config.nu and env.nu, then restart Nushell to regenerate defaults
  • Check syntax with nu --config /path/to/config.nu -c "exit" before setting as default

Plugins not loading

  • Ensure plugin binaries are in PATH
  • Register plugins explicitly: register /path/to/plugin

Windows: ANSI color issues

  • Set $env.config.use_ansi_coloring = true in config.nu
  • For older Windows versions, enable Virtual Terminal processing

Platform-Specific Notes

macOS: If building from source fails with framework errors, ensure Xcode Command Line Tools are installed and accepted: sudo xcodebuild -license accept

Windows: For full functionality including process management, use Windows Terminal rather than legacy console host.

Linux: For proper file system watching and process management, ensure inotify limits are sufficient: echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf

← Project overviewView alternatives to nushell/nushell →