xenv

English | 简体中文

xenv is a local development environment manager for SDK versions, environment variables, and PATH entries. It is designed for developers who switch between projects that need different toolchains or local runtime settings.

• Discover and activate locally installed SDKs, such as Go and Node.js.
• Manage global, project-local, and shell-session environment variables.
• Manage global, project-local, and shell-session PATH entries.
• Load project state from .xenv.toml when you enter a directory through the shell integration.
• Check effective SDKs and project tool requirements.
• Generate shell hooks for bash, zsh, PowerShell, and cmd/clink.

Install by Eget:

eget install inhere/xenv

Install the latest version with Go:

go install github.com/inhere/xenv/cmd/xenv@latest

Enable shell integration first. This lets xenv use, xenv set, and xenv path add update the current shell instead of only printing shell script output.

Bash:

eval "$(xenv shell --type bash)"

Zsh:

eval "$(xenv shell --type zsh)"

PowerShell:

Invoke-Expression (&xenv shell --type pwsh)

Initialize the default configuration explicitly if you want to create it before first use:

xenv config init

The default configuration file is created at:

~/.config/xenv/config.yaml

Then index locally installed SDKs and activate a version:

xenv sdk index
xenv sdk list
xenv use go:latest

Save project-local settings to .xenv.toml:

xenv use -s go:1.24
xenv set -s APP_ENV local
xenv path add -s ./bin

Inspect status and run checks:

xenv status
xenv check

Generate shell integration scripts:

xenv shell --type bash
xenv shell --type zsh
xenv shell --type pwsh
xenv shell --type cmd

Install the hook into your shell profile:

# PowerShell
xenv shell --install -t pwsh --profile $PROFILE.CurrentUserAllHosts

# bash or zsh
xenv shell --install -t $SHELL

PowerShell can also load the hook directly:

Invoke-Expression (&xenv shell --type pwsh)
# or
xenv shell --type pwsh | Out-String | Invoke-Expression

When shell integration is active, xenv keeps a shell-session state file and can automatically load matching .xenv.toml files when you change directories.

Most environment-changing commands support four scopes:

Examples:

# Current shell session
xenv use go:latest
xenv set APP_ENV local
xenv path add ./bin

# Project .xenv.toml
xenv use -s go:1.24
xenv set -s APP_ENV local
xenv path add -s ./bin

# Global state
xenv use -g go:1.24
xenv set -g GOPROXY https://proxy.golang.org,direct
xenv path add -g ~/.local/bin

# OS user environment
xenv set -S GOPROXY https://proxy.golang.org,direct
xenv unset -S GOPROXY
xenv path add -S ~/.local/bin
xenv path remove -S ~/.local/bin

-S/--system can not be combined with -g/--global or -s/--direnv. New PATH entries are prepended, so they take priority. Run xenv from a hooked shell to also update the current shell immediately.

xenv run (alias exec) builds an SDK/ENV/PATH environment from options and runs a command inside it. Nothing is written to xenv state and no shell hook is required, so it also works from editors, CI runners and GUI-launched processes.

xenv run -u go:1.24,node:22 -p ./bin -e APP_ENV=local -- go build ./...
xenv exec -u go:1.24 --cwd D:/work/proj -- go test ./...
xenv run -u go --print -- go version

Rules:

• ENV order: inherited environment, then SDK active_env, then --env; the last value wins.
• PATH order: --path entries, then SDK bin directories, then the inherited PATH; duplicate entries are dropped and new entries win.
• Options of the target command must be placed after --, otherwise they are parsed as xenv run options.
• The exit status is the child's status, 127 when the command is not found and 2 for xenv side errors.

• xenv status: Show current state for this directory and shell, including Effective State, Session Context, and Runtime State.
• xenv sdk list: List local SDK inventory.
• xenv env list: List xenv-managed environment variable state.
• xenv path list: List xenv-managed PATH state.
• xenv check: Check whether Effective State and project tool requirements are satisfied.

Top-level xenv list / xenv ls is not kept in v0; use xenv status for state diagnostics.

Project state is stored in .xenv.toml. The shell hook can load it automatically when you enter the project directory.

Example:

paths = [
  "./bin",
  "windows:C:/Program Files (x86)/NSIS",
  "linux:/opt/nsis/bin",
  "darwin:/opt/homebrew/bin",
]

[sdks]
go = "1.24"
node = "20"
flutter = "windows:3.27"

[envs]
APP_ENV = "local"

[tools]
rg = "*"
golangci-lint = ">=1.60,required"

Sections:

• paths: Project-local entries added to PATH. Prefix an entry with windows:, linux:, or darwin: to load it only on that OS; the prefix is stripped before adding it to PATH.
• sdks: SDK versions activated for the project. Prefix a version with windows:, linux:, or darwin: to activate it only on that OS; the prefix is stripped before version matching.
• envs: Environment variables loaded for the project.
• tools: External tool requirements checked by xenv check tools.

When source_project_scripts: true is set in config.yaml, entering a directory also sources project scripts: .xenv.sh / .xenv.ps1 and a compatible .envrc (bash/zsh) or .envrc.ps1 (pwsh) found in the directory or its parents. Keep this disabled for untrusted directories, since those files run with your shell's privileges.

Each init-direnv run records what it applied to the current shell in the XENV_APPLIED_DIRENV environment variable (a JSON record: applied .xenv.toml, added PATH entries, changed variables with their previous values, activated SDKs).

• cd into another project or out of the project: the recorded PATH entries are removed, variables are restored to their previous values (unset when they were not set before), and the new directory is applied in the same shell command.
• cd inside the same project (including subdirectories): nothing is re-applied or reverted.
• -s/--direnv commands (use -s, set -s, unset -s, path add/remove -s) update the record too, so their effect is reverted on leave.
• The record lives in the shell environment only: it is per-shell, disappears with the shell, and is never written to state files.

Not reverted on leave:

• source_project_scripts / .envrc side effects, since the scripts run in your current shell (keep the option off for directories you do not trust).
• Changes made outside xenv (for example editing PATH yourself), and removals that were not recorded.
• -g/--global and -S/--system changes, which are not directory scoped.

Use xenv status --layers to inspect the current record.

SDKs are configured in config.yaml, then indexed from local installation directories.

Common commands:

xenv sdk index
xenv sdk list
xenv sdk list --all
xenv sdk show go
xenv sdk where go:1.24
xenv sdk where --bin go:1.24
xenv sdk which go:1.24

Version specs can use either name:version or name@version:

xenv use go:1.24
xenv use node@20

When the version is omitted, latest is used:

xenv use go
xenv use go:latest
xenv use go:stable

latest and stable both resolve to the highest installed version. Other aliases such as lts are not supported yet and fail with a message asking for an explicit version.

Activate or deactivate multiple SDKs at once:

xenv use go:1.24 node:20
xenv unuse go:1.24 node:20

List environment variables managed by xenv:

xenv env
xenv env list

Set and unset values:

xenv env set APP_ENV=local
xenv env set APP_ENV=local DEBUG=true
xenv env set APP_ENV local
xenv env unset APP_ENV

env set accepts one or more KEY=VALUE pairs. When exactly two arguments are given and the first one contains no =, they are read as <name> <value> (the original form).

Top-level shortcuts are also available:

xenv set APP_ENV local
xenv unset APP_ENV

Use -s for project state or -g for global state:

xenv set -s APP_ENV local
xenv unset -g GOPROXY

Use -S to write to the OS user environment, so new processes read the value without the xenv hook:

xenv set -S GOPROXY https://proxy.golang.org,direct
xenv unset -S GOPROXY

On Windows the value is written to HKCU\Environment; on Linux/macOS it is written to the xenv block of ~/.bashrc or ~/.zshrc. -S can not be combined with -g or -s.

List the OS user environment variables in addition to the xenv-managed state:

xenv env list -S

List managed PATH entries:

xenv path
xenv path list

Add, remove, and search entries:

xenv path add ./bin
xenv path remove ./bin
xenv path search go

Use -s for project state or -g for global state:

xenv path add -s ./bin
xenv path add -g ~/.local/bin

Use -S to add or remove an entry in the OS user PATH:

xenv path add -S ~/.local/bin
xenv path remove -S ~/.local/bin

The entry is prepended, and the original value type and %VAR% references are preserved on Windows. Adding or removing a path that does not change anything fails with a message instead of writing a duplicate entry.

List the OS user PATH entries in addition to the xenv-managed state:

xenv path list -S

Run all checks:

xenv check

Check SDK availability for Effective State:

xenv check sdk

Check project tool requirements from .xenv.toml:

xenv check tools

Tool requirements live under [tools]:

[tools]
rg = "*"
golangci-lint = ">=1.60,required"

Default files:

~/.config/xenv/config.yaml
~/.config/xenv/global.toml
~/.config/xenv/session/<session_id>.json
~/.config/xenv/sdks.local.json
~/.config/xenv/hooks

Show the active configuration summary:

xenv config

Read selected configuration values:

xenv config get bin_dir
xenv config get shell_hooks_dir

Edit the configuration file with $XENV_EDITOR, $VISUAL or $EDITOR:

xenv config --edit

Export configuration:

xenv config export zip
xenv config export json

Configuration files support environment variable expansion in values, for example ${HOME} or ${XENV_SDK_ROOT}.

Example config.yaml:

bin_dir: "~/.local/bin"
eget_enable: false
eget_store_file: ""
check_tools_on_direnv: false
source_project_scripts: false
allow_up_match: 1
shell_hooks_dir: "~/.config/xenv/hooks"
global_env: {}
global_paths: []
sdks:
  - name: go
    alias: golang
    install_dir: "${XENV_SDK_ROOT}/go{version}"
    bin_dir: "bin"
    active_env:
      GOROOT: "{install_dir}"
  - name: node
    install_dir: "${XENV_SDK_ROOT}/node-v{version}"
    bin_dir: "bin"

SDK fields:

Aliases:

• xenv sdks for xenv sdk
• xenv st for xenv status
• xenv e for xenv env
• xenv p for xenv path
• xenv cfg for xenv config
• xenv sdk refresh or xenv sdk scan for xenv sdk index
• xenv sdk which for xenv sdk where
• xenv path rm or xenv path delete for xenv path remove

Run tests:

go test ./...

Build without release compression:

go build ./cmd/xenv

Build with the project Makefile:

make build

The Makefile uses UPX for compression on supported targets, so upx must be available for those build targets.