is-wsl

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.

Package Information

• Package Name: is-wsl
• Package Type: npm
• Language: JavaScript (with TypeScript declarations)
• Installation: npm install is-wsl

Core Imports

import isWsl from 'is-wsl';

For CommonJS environments:

// This package is ES modules only - use dynamic import in CommonJS
(async () => {
  const { default: isWsl } = await import('is-wsl');
  console.log(isWsl); // boolean value
})();

// Or in async function
async function checkWsl() {
  const { default: isWsl } = await import('is-wsl');
  return isWsl;
}

Basic Usage

import isWsl from 'is-wsl';

// Check if running inside WSL
if (isWsl) {
  console.log('Running inside Windows Subsystem for Linux');
  // Apply WSL-specific workarounds or configurations
} else {
  console.log('Not running inside WSL');
  // Standard behavior for native Linux/Windows/macOS
}

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

const config = {
  useNativeFileWatching: !isWsl, // Disable on WSL due to bugs
  pathSeparator: isWsl ? '/' : path.sep,
};

Capabilities

WSL Detection

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

/**
 * Boolean constant indicating whether the current process is running inside WSL
 * - Returns true if running inside WSL 1 or WSL 2
 * - Returns false on all other platforms (Windows, macOS, native Linux)
 * - Returns false when running inside containers within WSL
 * - Value is computed once at module load time
 * 
 * Note: When __IS_WSL_TEST__ environment variable is set, 
 * exports the detection function instead of the computed boolean
 */
declare const isWsl: boolean;

export default isWsl;

Detection Logic:

The detection works by examining multiple system indicators:

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

Supported Scenarios:

• ✅ WSL 1 detection (older Linux kernel with Microsoft signature)
• ✅ WSL 2 detection (newer Linux kernel with Microsoft signature)
• ✅ Native Linux systems (returns false)
• ✅ Windows and macOS (returns false)
• ✅ Container environments in WSL (returns false to avoid false positives)
• ✅ Error handling (graceful fallback to false if filesystem reads fail)

Types

/**
 * Normal export: boolean constant indicating WSL environment
 * When __IS_WSL_TEST__ is not set (production usage)
 */
declare const isWsl: boolean;

/**
 * Test mode export: detection function for testing
 * When __IS_WSL_TEST__ environment variable is set
 */
declare function isWsl(): boolean;

// The actual export depends on the __IS_WSL_TEST__ environment variable
export default isWsl;

Error Handling

The library handles all potential errors gracefully:

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

Platform Support

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

Dependencies

• Runtime: is-inside-container@^1.0.0 - Used to detect container environments
• Dev Dependencies: Testing and linting tools only

Environment Variables

• __IS_WSL_TEST__: When set, exports the detection function instead of the computed value (used internally for testing)

Test Mode API

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

// Set environment variable before importing
process.env.__IS_WSL_TEST__ = 'true';

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

// Call the function to get the result
const result = isWslFunction(); // returns boolean
console.log(typeof isWslFunction); // 'function'
console.log(typeof result); // 'boolean'

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