Repository navigation
Handle Nushell vendor autoload mismatch when XDG variables are set in config.nu #2491
Description
As discussed in the thread at #2346 (comment), the installer may resolve a different Nushell vendor autoload directory from the session that launched it. This is a follow-up and does not block the current directory layout work.
The installer discovers the user-local vendor autoload directory by starting a new Nushell process and reading $nu.vendor-autoload-dirs:
nu -c '$nu.vendor-autoload-dirs | reverse | each {|dir| $dir } | str join (char nl)'Nushell resolves XDG_CONFIG_HOME and XDG_DATA_HOME at startup. Its documentation states that these variables must be set before Nushell is launched:
https://www.nushell.sh/book/configuration.html#changing-default-directories
If Nushell starts without XDG_DATA_HOME in its parent environment and config.nu later sets it to /custom/data, the current session continues using the autoload directories that were resolved before config.nu was loaded. However, the installer inherits the updated environment and starts a new nu -c process, which selects /custom/data/nushell/vendor/autoload.
A new top-level Nushell started from a parent where XDG_DATA_HOME is still unset will again resolve its original autoload directory before loading config.nu. As a result, the installer may report that Nushell was configured successfully while normal new sessions do not load the generated vite-plus.nu.
Although setting these variables in config.nu is outside Nushell’s documented startup model, leaving XDG_DATA_HOME unset is common, and managing environment variables in config.nu is a natural choice for users.
As a follow-up, we should confirm this behavior with an integration test and decide whether to handle the mismatch, warn about it, or document that XDG startup variables must be provided by Nushell’s parent process.
I can take responsibility for this task after the current PR is merged.
Metadata
Metadata
Assignees
Labels
Type
Fields
Priority
Activity
naokihaba commentedon Sep 14, 2026
This issue happens because
XDG_DATA_HOMEis left unset when Nushell starts and is only defined later inconfig.nu. According to the documentation, Nushell explicitly requires these environment variables to be set before the shell launches so it can properly configure its data and autoload directories.While setting the variable in
config.nuis valid Nushell syntax, it only affects child processes. It doesn't update the autoload paths that the current session has already resolved, so this behavior is expected based on how Nushell is designed to work.I verified this on macOS using the Vite+ standalone installer and Nushell 0.115.1. The installation completes successfully, but a new session fails to load Vite+. On the other hand, if
XDG_DATA_HOMEis set before startup, Vite+ loads without any issues.I reproduced this on macOS running Nushell 0.115.1 with the standalone Vite+ installer.
XDG_DATA_HOMEis unset before startup and set inconfig.nuXDG_DATA_HOMEis set before Nushell startsIn both cases,
XDG_DATA_HOMEends up being set properly after startup. The core issue is simply which autoload directory Nushell resolved before loadingconfig.nu.I added reproduction tests in commit 4f1a2fc that assert this current behavior, including the path mismatch.
Per the Nushell docs, these directory variables have to be set before the shell launches. Setting
XDG_DATA_HOMEinsideconfig.nuis valid syntax and passes down to child processes, but it won't update the paths Nushell already resolved for the active session. Because of that, this setup doesn't meet the shell's documented startup requirements.I also looked into a few potential workarounds.
One option is to explicitly pass the launching session's autoload directory, which works even through Bash. However, that requires updating how the installer is invoked and adding support on that end.
Relying on user autoload only solves part of the problem. It handles the case where someone only modifies
XDG_DATA_HOME, but the mismatch comes right back if they also changeXDG_CONFIG_HOMEinconfig.nu.Besides that, the original paths aren't exported automatically. In an isolated test environment, child processes picked up the updated XDG values, but not the original configuration or autoload paths from the parent session.
Finally, just warning users whenever
XDG_DATA_HOMEis set would cause false positives for valid setups, since checking for the variable doesn't tell us how or when it was configured.docs: clarify Nushell XDG startup requirements and recovery (#2704)
chore(deps): update rust crates (#1780)