From dc99cff3803543c2c44ec38512153b64d6747192 Mon Sep 17 00:00:00 2001 From: James Smith Date: Fri, 2 Jan 2026 18:47:23 +0200 Subject: [PATCH] Document deprecation of $env.NU_LIB_DIRS The $env.NU_LIB_DIRS has been marked deprecated in the nushell source code for a while now, by default it is an empty list to maintain compatibility. Users should prefer the constant $NU_LIB_DIRS instead, which is populated with some things based on environment variables at nushell startup. The docs had drifted a bit. This commit serves to update them. --- book/configuration.md | 6 +++--- book/modules/creating_modules.md | 2 +- book/modules/using_modules.md | 6 +++--- book/special_variables.md | 6 ++++++ 4 files changed, 13 insertions(+), 7 deletions(-) diff --git a/book/configuration.md b/book/configuration.md index c5610e1aff2..62448628808 100644 --- a/book/configuration.md +++ b/book/configuration.md @@ -390,12 +390,12 @@ The variables that affect Nushell file locations are: Once Nushell starts, this value is stored in the `$nu.default-config-dir` constant. See [Using Constants](#using-constants) below. -- `$env.XDG_DATA_HOME`: If this environment variable is set, Nushell sets the `$nu.data-dir` constant to this value. The `data-dir` is used in several startup tasks: +- `$env.XDG_DATA_HOME`: If this environment variable is set, Nushell sets the `$nu.data-dir` constant to `($env.XDG_DATA_HOME)/nushell`. The `data-dir` is used in several startup tasks: - - `($nu.data-dir)/completions` is added to the `$env.NU_LIB_DIRS` search path. + - `($nu.data-dir)/completions` is added to the `const` variable `$NU_LIB_DIRS` search path. (Note: `$env.NU_LIB_DIRS` is not populated by default and is currently deprecated. See [Special Variables - `$env.NU_LIB_DIRS`](./special_variables.md#env-NU_LIB_DIRS).) - `($nu.data-dir)/vendor/autoload` is added as the last path in `nu.vendor-autoload-dirs`. Files in this directory will be read after the other vendor-auto-load directories, thus overriding any of their settings. - Note that the directory represented by `$nu.data-dir`, nor any of its subdirectories, are created by default. Creation and use of these directories is up to the user. + Note that the directory represented by `$nu.data-dir`, including any of its subdirectories, are NOT created by default. Creation and use of these directories is up to the user. - `$env.XDG_DATA_DIRS` _(Unix Platforms Only)_: If this environment variable is set, it is used to populate the `$nu.vendor-auto-load` directories in the order listed. The first directory in the list is processed first, meaning the last one read will have the ability to override previous definitions. diff --git a/book/modules/creating_modules.md b/book/modules/creating_modules.md index 0c5118e9fc7..c01372acaa2 100644 --- a/book/modules/creating_modules.md +++ b/book/modules/creating_modules.md @@ -305,7 +305,7 @@ Also notice that, because the commands from `increment` and `range-into-list` ar ## Environment Variables -Modules can define an environment using [`export-env`](/commands/docs/export-env.md). Let's extend our `my-utils` module with an environment variable export for a common directory where we'll place our modules in the future. This directory is (by default) in the `$env.NU_LIB_DIRS` search path discussed in [Using Modules - Module Path](./using_modules.md#module-path). +Modules can define an environment using [`export-env`](/commands/docs/export-env.md). Let's extend our `my-utils` module with an environment variable export for a common directory where we'll place our modules in the future. This directory is (by default) in the `$NU_LIB_DIRS` search path discussed in [Using Modules - Module Path](./using_modules.md#module-path). ```nu # A collection of helpful utility functions diff --git a/book/modules/using_modules.md b/book/modules/using_modules.md index 55436de5bc1..ecca9472301 100644 --- a/book/modules/using_modules.md +++ b/book/modules/using_modules.md @@ -69,13 +69,13 @@ The path to the module can be: Note that the module name (its directory) can end in a `/` (or `\` on Windows), but as with most commands that take a paths (e.g., `cd`), this is completely optional. ::: - ::: important Important! Importing modules from `$env.NU_LIB_DIRS` - When importing a module via a relative path, Nushell first searches from the current directory. If a matching module is not found at that location, Nushell then searches each directory in the `$env.NU_LIB_DIRS` list. + ::: important Important! Importing modules from `$NU_LIB_DIRS` or `$env.NU_LIB_DIRS` + When importing a module via a relative path, Nushell first searches from the current directory. If a matching module is not found at that location, Nushell then searches each directory in the constant `$NU_LIB_DIRS` list, and then `$env.NU_LIB_DIRS`. This allows you to install modules to a location that is easily accessible via a relative path regardless of the current directory. ::: -- An absolute or relative path to a Nushell module file. As above, Nushell will search the `$env.NU_LIB_DIRS` for a matching relative path. +- An absolute or relative path to a Nushell module file. As above, Nushell will search the constant `$NU_LIB_DIRS` and then `$env.NU_LIB_DIRS` for a matching relative path. ::: details Example diff --git a/book/special_variables.md b/book/special_variables.md index 69373283161..da4aba5d3e7 100644 --- a/book/special_variables.md +++ b/book/special_variables.md @@ -100,6 +100,12 @@ try { ### `$env.NU_LIB_DIRS` +::: note + +As of version 0.101.0, this environment variable is marked as deprecated. Users should prefer the `$NU_LIB_DIRS` constant (see below). + +::: + A list of directories which will be searched when using the `source`, `use`, or `overlay use` commands. See also: - The `$NU_LIB_DIRS` constant below