UPSTREAM PR #17563: Update how $NU_LIB_DIRS / $env.NU_LIB_DIRS is handled at startup time

[loci-dev]

Note

Source pull request: nushell/nushell#17563

This PR changes how (really where) NU_LIB_DIRS and $env.NU_LIB_DIRS gets set. Specifically, it was written and tested with these two use cases in mind for packagers.

Usecase 1 - using the nu -I

❯ nu -I /home/fdncred/vouch-git:/some/path1:/some/path2 -c 'print $env.NU_LIB_DIRS;use vouch *;vouch main'
╭───┬────────────────────────────────────────────────╮
│ 0 │ /home/fdncred/.config/nushell/scripts          │
│ 1 │ /home/fdncred/.local/share/nushell/completions │
│ 2 │ /home/fdncred/vouch-git                        │
│ 3 │ /some/path1                                    │
│ 4 │ /some/path2                                    │
╰───┴────────────────────────────────────────────────╯
Usage: vouch <command>

Local Commands:
  add               Add a user to the vouched contributors list
  check             Check a user's vouch status
  denounce          Denounce a user by adding them to the vouched file
  remove            Remove a user from the vouched contributors list

GitHub integration:
  gh-check-pr         Check if a PR author is a vouched contributor
  gh-manage-by-discussion Manage contributor status via discussion comment
  gh-manage-by-issue  Manage contributor status via issue comment

Usecase 2 - Using NU_LIB_DIRS

❯ NU_LIB_DIRS=/home/fdncred/vouch-git:/some/path1:/some/path2 nu -c 'print $env.NU_LIB_DIRS;use vouch *;vouch main'
╭───┬────────────────────────────────────────────────╮
│ 0 │ /home/fdncred/.config/nushell/scripts          │
│ 1 │ /home/fdncred/.local/share/nushell/completions │
│ 2 │ /home/fdncred/vouch-git                        │
│ 3 │ /some/path1                                    │
│ 4 │ /some/path2                                    │
╰───┴────────────────────────────────────────────────╯
Usage: vouch <command>

Local Commands:
  add               Add a user to the vouched contributors list
  check             Check a user's vouch status
  denounce          Denounce a user by adding them to the vouched file
  remove            Remove a user from the vouched contributors list

GitHub integration:
  gh-check-pr         Check if a PR author is a vouched contributor
  gh-manage-by-discussion Manage contributor status via discussion comment
  gh-manage-by-issue  Manage contributor status via issue comment

Release notes summary - What our users need to know

Changes how (really where) NU_LIB_DIRS and $env.NU_LIB_DIRS gets set. Specifically. so they can be used with:

• nu -c like NU_LIB_DIRS=/some/path nu -c 'print $env.NU_LIB_DIRS;use some_module *;some_module main'
• nu -I /some/path -c 'print $env.NU_LIB_DIRS;use some_module *;some_module main'

Details

• It synchronizes $NU_LIB_DIRS and $env.NU_LIB_DIRS at startup
• Both $NU_LIB_DIRS and $env.NU_LIB_DIRS contain defaults and user-specified paths and provided paths append to the list
• Allows backwards compatibility with -I '\x1e for path separation as well as allows traditional /some/path1:/some/path2 or /some/path1;/some/path2 for Windows.
• A little refactor to consolidate code and adjusted some tests

Tasks after submitting

Our plan is still to deprecate $env.NU_LIB_DIRS in favor of const $NU_LIB_DIRS but until that time, I'm hoping this little fix makes it work for the people who need it.

• Update the documentation

[loci-review]

Overview

Analysis of Nushell binary target.aarch64-unknown-linux-gnu.release.nu across 34,872 functions reveals minimal performance impact from a focused maintenance update. Function changes: 47 modified, 87 new, 88 removed, 34,650 unchanged. Power consumption increased 0.29% (926,590.97 nJ → 929,289.66 nJ, +2,698.70 nJ).

The update implements NU_LIB_DIRS initialization refactoring to improve library path handling for packagers, adding 22ms to startup time. Performance-critical hot paths (IR execution, pipeline data flow, REPL loop) remain unaffected.

Function Analysis

Startup Functions (One-Time Cost):

• main: +252ns throughput (+4.4%), +21.67ms response time (+1.96%). Refactored NU_LIB_DIRS initialization adds parse_path_list() helper supporting multiple path separators, improving correctness for packagers.
• parse_cli_args_from_env: +13.8µs response time (+11.62%), stable throughput. Downstream effects from initialization refactoring.

Standard Library Regressions (External Code):

• Vec::from_iter: +1.74µs response time (+60.8%), stable throughput. Rust stdlib function showing allocator-related regression in called functions, not the collection logic itself. Used extensively (636+ sites) in Record construction and IR execution.
• FnOnce::call_once: +1.73µs response time (+33.5%), stable throughput. Compiler-generated trampoline showing regression in invoked closures, not the trampoline itself.
• rust_oom: +109ns response time (+194%). OOM handler only executes during memory exhaustion; irrelevant to normal operation.

Network Operation Improvements (External Dependencies):

• h2::decode_frame: -5.5µs response time (-6.1%). HTTP/2 frame decoding improved from h2 crate updates.
• h2::HeaderBlock::load: -1.43µs response time (-34.1%). HTTP/2 header processing optimization.
• http::PathAndQuery::from_shared: -27ns response time (-5.8%). URI parsing improved from http crate v1.4.0 updates.

Other analyzed functions (test utilities, version command, SQLite operations, MCP transport) showed minor changes with negligible impact on typical workloads.

Additional Findings

The NU_LIB_DIRS refactoring prioritizes correctness over raw performance: environment variables are now properly converted to Nushell Values before use, multiple path separators are supported (:, ;, \x1e), and const declarations prevent accidental runtime modifications. The 22ms startup overhead is justified for improved packager compatibility and cross-platform robustness. No GPU or ML operations were identified in the analyzed functions.

🔎 Full breakdown: Loci Inspector.
💬 Questions? Tag @loci-dev.