wslenv
wslenv is a small helper script intended to populate and print environment variables that are useful when running inside WSL (Windows Subsystem for Linux) - especially when those variables are missing.
It detects WSL, prepares distro info, configures interop, and merges the Windows PATH. Optionally, it prepares WSLg-related GUI variables.
At the end, it prints shell-ready export commands for any variables it had to set.
Rationale
Why you need it There are situations where you end up inside a WSL distribution without the expected interop variables. For example:
- Log into it via SSH. I.e. you have in your
~/.ssh/config:Host wsldistr-inside-winhost ProxyCommand ssh winhost wsl -d wsldistr -u root sshd -i
- After
sudo -H -i.
Installation
If you want it only as a program available in your PATH, use pipx:
pipx install wslenv
If you want to have development version:
$ git clone https://github.com/pyhedgehog/wslenv.git
$ cd wslenv
$ pipx install -e .
Usage
# wslen --help
usage: wslenv [-h] [--no-gui] [--unset]
Script to investigate environment variables useful in WSL if missing.
options:
-h, --help show this help message and exit
--no-gui, --no-wslg, --plain, -p
Skip WSLg variables.
--unset, -u Unset WSL/WSLg variables.
Varibles: PATH, WSL_DISTRO_NAME, WSL_INTEROP, WSLENV, *(vars from WSLENV);
WSLg variables: DISPLAY, PULSE_SERVER, WAYLAND_DISPLAY, WSL2_GUI_APPS_ENABLED, XDG_RUNTIME_DIR
Typical usage is to evaluate wslenv output in your shell or in your script (i.e. in ~/.profile:
eval "$(wslenv)"
If you want to skip WSLg variables:
eval "$(wslenv --no-gui)"
If you want to unset WSLg variables (keeping WSL variables):
eval "$(wslenv --unset --no-gui)"
If you want to unset all WSL variables:
eval "$(wslenv --unset)"
What it sets
Core WSL variables
WSL_INTEROP- detects the nearest parent WSL interop relayWSL_DISTRO_NAME- useswslpath -w /WSLENV- gets WindowsWSLENVor sets it to emptyPATH- merges WindowsPATHentries into the LinuxPATH(avoids duplicates)
Also variables mentioned in WSLENV can be set.
Optional WSLg variables (GUI apps)
When GUI support is detected and --no-gui / --no-wslg is not used:
WAYLAND_DISPLAYPULSE_SERVERXDG_RUNTIME_DIRDISPLAYWSL2_GUI_APPS_ENABLED
Notes
The script relies on WSL interop utilities:
wslpath -m /wslinfo --msal-proxy-pathcmd.exe /c set
There are some corner cases:
- All variables processed by wslenv and wsl itself can has different result.
Normal wsl startup procedure first sets wsl-specific variables and the processes shell's profile.
But when you use
eval $(wslenv)(even in.bashrc) you already has initial setup done. - Any wsl-specific variable (including mentioned in
$WSLENV) set by wslenv only if it not set from some other source. $PATHand*/lvariables mentioned in$WSLENVprocessed differently - paths from windows%Path%added to$PATH, but variables from WSLENV defined only if they are not already defined in current environment.
Roadmap
- Run command in modified environment (like
wslenv -c cmd.exe /c echo %PATH%). - Check in fresh
wslc.execontainers. - Make OS packages (at least for Alpine and Ubuntu as sane and default WSL distributions).
- Detect WSL kernel version and process corner cases if found.
- Make minimal version - i.e. without python dependencies (shell or compilable - C/Ninja/Rust/codon/...).
- Plugins? No idea what for. :-(
Help wanted
- Would anyone be willing to help improve this documentation?
- Documentation for using it as a module too. https://github.com/pyhedgehog/wslenv/pulls
- Double-check WSLENV corner-cases in different versions of WSL:
- UPPER/lower chars in variable names. See https://github.com/Microsoft/WSL/issues/8639
- Special chars in variable names. See https://github.com/Microsoft/WSL/issues/10697
- Relative paths when converted by
/pand/l. See https://github.com/Microsoft/WSL/issues/5274 - Non-local paths
\\remote\share\pathin%PATH%or/pl. - WSL distribion specific paths. See https://github.com/microsoft/WSL/issues/3725#issuecomment-5409636503
- Watch for future WSL features related to env processing:
- Globs (
WSLENV=JAVA*/lto set all variables starting withJAVA). See - Append to path-like variables. See https://github.com/Microsoft/WSL/issues/6020
- Converting variable names. See https://github.com/Microsoft/WSL/issues/5341
- Forced setting of variables. See https://github.com/Microsoft/WSL/issues/10697
- Replace
cmd.exe /c setwith better alternative. See https://github.com/Microsoft/WSL/issues/12504
- Globs (
- Maybe you can invent something more? https://github.com/pyhedgehog/wslenv/issues
Changelog
0.2.0 (2026-09-01)
- Support for unsetting variables using
wslenv -u. - Import from Windows variables mentioned in inherited or imported
WSLENV.
0.1.0 (2026-07-28)
0.0.0 (2026-07-20)
- Never released.
- First usable code.
Metadata
Release files for wslenv 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| wslenv-0.2.0.tar.gz | 7.1 kB | Without provenance | Details for wslenv-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wslenv-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for wslenv-0.2.0-py3-none-any.whl |
Total release size: 15.2 kB
Release files / wslenv-0.2.0.tar.gz
| Download URL | wslenv-0.2.0.tar.gz |
|---|---|
| Size | 7.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
352ee46ecc01ca8c82505b639dc2f4ef4aae8da26b18283bfbef90f60f5527e5
|
|
BLAKE2b-256 checksum How to use checksums |
8da7fa43f749ebfd777d61f9327343060d54550e3571e43037ba09e86bbc08d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.3.4 CPython/3.12.10 Windows/10
|
Release files / wslenv-0.2.0-py3-none-any.whl
| Download URL | wslenv-0.2.0-py3-none-any.whl |
|---|---|
| Size | 8.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
deb1523b8c7f784c9c9dee4441a05fabd99aedff1cf319c7b819cfc83f97b070
|
|
BLAKE2b-256 checksum How to use checksums |
64ffaf4cdc9a9545a6756588bf2ab36b479ad7abba0e120d7e4e2aa5a000e9d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.3.4 CPython/3.12.10 Windows/10
|
Security for wslenv 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.