INI File Parser and Serializer

6.0.0 · active · verified Sun Apr 19

The `ini` package provides a robust encoder and decoder for INI file formats in Node.js environments. As of version 6.0.0, it targets Node.js `^20.17.0 || >=22.9.0`. The library is actively maintained, with frequent major version bumps primarily driven by updates to supported Node.js engine ranges. Key features include parsing INI strings into nested JavaScript objects, handling section-less items as globals, and supporting bracketed arrays (e.g., `key[] = value`). It also offers comprehensive serialization with options for whitespace, alignment, sorting of sections and keys, platform-specific line endings, and custom section identifiers. It differentiates itself by offering fine-grained control over output format and careful handling of common INI parsing quirks. The project maintains a healthy release cadence, with at least one new version released in the past 12 months.

Common errors

```
The "ini" package is not compatible with your Node.js version. Requires: ^20.17.0 || >=22.9.0
```
cause Your Node.js version does not meet the minimum requirements specified in the `engines` field of the `ini` package's `package.json` for the installed version (6.0.0).

fix Upgrade your Node.js environment to a compatible version (e.g., Node.js 20.17.0+ or 22.9.0+), or downgrade the `ini` package to a version compatible with your current Node.js setup (e.g., `npm install ini@4` for older Node.js LTS versions).
```
TypeError: ini.parse is not a function OR ini.stringify is not a function (when using require())
```
cause This error typically occurs when attempting to use CommonJS `require()` syntax with an ESM-first package that only exposes named exports or has different CJS entry points, or if the `require` call is incorrect.

fix For modern Node.js environments (which `ini` v3+ targets), use ESM `import` statements: `import { parse, stringify } from 'ini';`. If you must use CommonJS, ensure your `package.json` configuration properly handles dual CommonJS/ESM exports, or consult the package's `exports` field if available.
```
Unexpected output format from `ini.stringify` (e.g., missing spaces around `=`, or array format issues)
```
cause The default options for `ini.stringify` (like `whitespace: false` and `bracketedArray: true`) may not align with your expected INI format or the requirements of another INI parser.

fix Explicitly configure the `stringify` options to match your desired output. For example, `stringify(obj, { whitespace: true, bracketedArray: false })`.

Warnings

breaking Version 6.0.0 introduces a breaking change by tightening Node.js engine compatibility, now requiring Node.js `^20.17.0 || >=22.9.0`. Ensure your environment meets these requirements before upgrading.
Fix: Upgrade Node.js to a compatible version (e.g., Node.js 20.17.0+ or 22.9.0+) or pin `ini` to an earlier major version if an upgrade is not feasible.
breaking Version 5.0.0 updated Node.js engine compatibility to `^18.17.0 || >=20.5.0`. Projects on older Node.js versions must upgrade Node.js or remain on `ini` v4.x.
Fix: Upgrade Node.js to a compatible version (e.g., Node.js 18.17.0+ or 20.5.0+) or pin `ini` to a v4.x release.
breaking Version 3.0.0 dropped support for Node.js 10 and non-LTS versions of Node.js 12 and 14, requiring Node.js `^14.17.0 || ^16.13.0 || >=18.0.0` for v4.0.0. Projects using these older Node.js versions will break upon upgrade.
Fix: Upgrade Node.js to a supported LTS version (e.g., Node.js 14.17.0+, 16.13.0+, or 18.0.0+) or use `ini` v2.x.
gotcha When using `stringify`, the `whitespace` option defaults to `false`. This can result in INI output like `key=value` instead of `key = value`. If you require spaces for readability or compatibility with specific parsers, explicitly set `whitespace: true` or use the `align: true` option which implies `whitespace: true`.
Fix: Pass `{ whitespace: true }` or `{ align: true }` as the options object to `stringify`.
gotcha The `stringify` function's `bracketedArray` option defaults to `true`, appending `[]` to array keys (e.g., `array[] = value`). While common, some older INI parsers might treat duplicate keys without brackets as arrays. Ensure this default matches your target parser's expectations.
Fix: If your parser expects duplicate keys without brackets for arrays, set `bracketedArray: false` in the options for `stringify`.
deprecated For backwards compatibility, passing a string directly as the second argument to `stringify` is treated as the `section` option. While still supported, it's recommended to pass an options object for clarity and to utilize other formatting options.
Fix: Always pass an options object, e.g., `stringify(obj, { section: 'mySection' })`.

Install

npm install ini npm
yarn add ini yarn
pnpm add ini pnpm

Imports

parse
wrong:
```
const parse = require('ini').parse
```
correct:
```
import { parse } from 'ini'
```
Primary function to convert INI string to object. The `decode` alias also exists. Modern Node.js projects should use ESM imports.
stringify
wrong:
```
const stringify = require('ini').stringify
```
correct:
```
import { stringify } from 'ini'
```
Primary function to convert an object to an INI string. The `encode` alias also exists. Modern Node.js projects should use ESM imports.
safe
wrong:
```
const safe = require('ini').safe
```
correct:
```
import { safe } from 'ini'
```
Utility to escape a string for use as a key or value in an INI file.
unsafe
wrong:
```
const unsafe = require('ini').unsafe
```
correct:
```
import { unsafe } from 'ini'
```
Utility to unescape a string previously escaped for an INI file.

Quickstart

This example demonstrates reading INI data, parsing it into a JavaScript object, modifying properties (including nested sections and arrays), and then stringifying the object back into an INI formatted string with a custom top-level section.

import { writeFile , readFile } from 'node:fs/promises'
import { stringify , parse } from 'ini'

const iniContent = `
; This comment is being ignored
scope = global

[database]
user = dbuser
password = dbpassword
database = use_this_database

[paths.default]
datadir = /var/lib/data
array[] = first value
array[] = second value
array[] = third value
`

async function manageIni() {
  // Simulate reading INI file content
  let text = iniContent;

  // Parse text data to object
  const config = parse(text)

  // Modify data object
  config.scope = 'local'
  config.database.database = 'use_another_database'
  config.paths.default.tmpdir = '/tmp'
  delete config.paths.default.datadir
  if (config.paths.default.array && Array.isArray(config.paths.default.array)) {
    config.paths.default.array.push('fourth value')
  }

  // Stringify data object with a section prefix
  text = stringify(config, {
    section : 'newSection',
    whitespace: true // Optional: Add spaces around = for readability
  })

  console.log('Modified INI content:\n', text)
  // In a real app, you'd write this back to a file:
  // await writeFile(`./Modified.ini`,text)
}

manageIni().catch(console.error);

view raw JSON →