0
# is-wsl
1

2
is-wsl is a lightweight utility that detects whether the current Node.js process is running inside Windows Subsystem for Linux (WSL). It provides a single boolean value that can be used to implement WSL-specific workarounds for unimplemented or buggy features. The library supports both WSL 1 and WSL 2 environments and handles edge cases like running inside containers.
3

4
## Package Information
5

6
- **Package Name**: is-wsl
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript declarations)
9
- **Installation**: `npm install is-wsl`
10

11
## Core Imports
12

13
```javascript
14
import isWsl from 'is-wsl';
15
```
16

17
For CommonJS environments:
18

19
```javascript
20
// This package is ES modules only - use dynamic import in CommonJS
21
(async () => {
22
  const { default: isWsl } = await import('is-wsl');
23
  console.log(isWsl); // boolean value
24
})();
25

26
// Or in async function
27
async function checkWsl() {
28
  const { default: isWsl } = await import('is-wsl');
29
  return isWsl;
30
}
31
```
32

33
## Basic Usage
34

35
```javascript
36
import isWsl from 'is-wsl';
37

38
// Check if running inside WSL
39
if (isWsl) {
40
  console.log('Running inside Windows Subsystem for Linux');
41
  // Apply WSL-specific workarounds or configurations
42
} else {
43
  console.log('Not running inside WSL');
44
  // Standard behavior for native Linux/Windows/macOS
45
}
46

47
// Since isWsl is a boolean constant, you can use it directly
48
import path from 'node:path';
49

50
const config = {
51
  useNativeFileWatching: !isWsl, // Disable on WSL due to bugs
52
  pathSeparator: isWsl ? '/' : path.sep,
53
};
54
```
55

56
## Capabilities
57

58
### WSL Detection
59

60
Provides a pre-computed boolean value indicating whether the process is running inside WSL.
61

62
```javascript { .api }
63
/**
64
 * Boolean constant indicating whether the current process is running inside WSL
65
 * - Returns true if running inside WSL 1 or WSL 2
66
 * - Returns false on all other platforms (Windows, macOS, native Linux)
67
 * - Returns false when running inside containers within WSL
68
 * - Value is computed once at module load time
69
 * 
70
 * Note: When __IS_WSL_TEST__ environment variable is set, 
71
 * exports the detection function instead of the computed boolean
72
 */
73
declare const isWsl: boolean;
74

75
export default isWsl;
76
```
77

78
**Detection Logic:**
79

80
The detection works by examining multiple system indicators:
81

82
1. **Platform Check**: Only returns `true` on Linux platforms (`process.platform === 'linux'`)
83
2. **OS Release**: Checks if `os.release()` contains "microsoft" (WSL identifier)
84
3. **Proc Filesystem**: Reads `/proc/version` to look for Microsoft signatures in the kernel version
85
4. **Container Detection**: Uses `is-inside-container` to avoid false positives when running inside Docker/containers within WSL
86

87
**Supported Scenarios:**
88

89
- ✅ WSL 1 detection (older Linux kernel with Microsoft signature)
90
- ✅ WSL 2 detection (newer Linux kernel with Microsoft signature)  
91
- ✅ Native Linux systems (returns false)
92
- ✅ Windows and macOS (returns false)
93
- ✅ Container environments in WSL (returns false to avoid false positives)
94
- ✅ Error handling (graceful fallback to false if filesystem reads fail)
95

96
## Types
97

98
```typescript { .api }
99
/**
100
 * Normal export: boolean constant indicating WSL environment
101
 * When __IS_WSL_TEST__ is not set (production usage)
102
 */
103
declare const isWsl: boolean;
104

105
/**
106
 * Test mode export: detection function for testing
107
 * When __IS_WSL_TEST__ environment variable is set
108
 */
109
declare function isWsl(): boolean;
110

111
// The actual export depends on the __IS_WSL_TEST__ environment variable
112
export default isWsl;
113
```
114

115
## Error Handling
116

117
The library handles all potential errors gracefully:
118

119
- **File System Errors**: If `/proc/version` cannot be read, defaults to `false`
120
- **Platform Compatibility**: Returns `false` immediately on non-Linux platforms
121
- **No Exceptions**: The public API never throws exceptions
122

123
## Platform Support
124

125
- **Node.js**: Requires Node.js >= 16
126
- **Platforms**: Designed for Linux environments, returns `false` on other platforms
127
- **WSL Versions**: Supports both WSL 1 and WSL 2
128
- **Containers**: Container-aware to prevent false positives
129

130
## Dependencies
131

132
- **Runtime**: `is-inside-container@^1.0.0` - Used to detect container environments
133
- **Dev Dependencies**: Testing and linting tools only
134

135
## Environment Variables
136

137
- **`__IS_WSL_TEST__`**: When set, exports the detection function instead of the computed value (used internally for testing)
138

139
## Test Mode API
140

141
When the `__IS_WSL_TEST__` environment variable is set, the module exports the detection function instead of the pre-computed boolean value:
142

143
```javascript { .api }
144
// Set environment variable before importing
145
process.env.__IS_WSL_TEST__ = 'true';
146

147
// Import will now export the function, not the boolean
148
import isWslFunction from 'is-wsl';
149

150
// Call the function to get the result
151
const result = isWslFunction(); // returns boolean
152
console.log(typeof isWslFunction); // 'function'
153
console.log(typeof result); // 'boolean'
154
```
155

156
This mode is used internally for testing different system configurations and should not be used in production code.