os-encoding

A cross-platform Node.js library to get the system's default character encoding.

Supports Windows, macOS, and Linux.

Installation

npm install os-encoding

Usage

const osEncoding = require('os-encoding');

// Get the system's default character encoding
console.log(osEncoding());
// Outputs: 'UTF-8', 'GBK', 'Windows-1252', etc.

console.log(`System encoding: ${osEncoding()}`);
// Output on Chinese Windows: "System encoding: GBK"
// Output on macOS/Linux: "System encoding: UTF-8"

API

osEncoding([envOnly]): string

Detects the system's default character encoding.

Returns the encoding name directly as reported by the OS or environment.

Parameters

Parameter	Type	Default	Description
envOnly	boolean	false	If true, only checks environment variables (LANG/LC_ALL) and skips executing fallback commands like locale or chcp.

Returns

• Type: string
• Description:
  • Raw encoding name (e.g., UTF-8, Shift_JIS, GBK).
  • Fallback: Returns UTF-8 if detection fails.

Platform-Specific Behavior

Platform	envOnly: true Behavior	envOnly: false (Default) Behavior
Windows	Ignores chcp command. Returns UTF-8 if no env vars.	Uses chcp when env vars are missing.
macOS	Ignores locale command. Returns UTF-8 if no env vars.	Uses locale when env vars are missing.
Linux	Same as macOS.	Same as macOS.

Notes

• Original Casing: Encoding names retain their OS-defined format:

  • UTF-8 (uppercase with hyphen)
  • Shift_JIS (underscore)
  • Windows-1252 (platform-specific casing)

• Detection Priority:

  1. Uses LANG or LC_ALL environment variables (macOS/Linux).
  2. Falls back to locale command or Windows chcp if environment variables are missing.

License

Copyright © 2025 SeaLoong