ini

library0.1jsnpmunverified

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.

serialization data

npm install ini

github ↗package ↗

INSTALL

IMPORT

SIG · INI

ini

serializationjavascriptv0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import { parse } from 'ini'

✗ const parse = require('ini').parse

Primary function to convert INI string to object. The `decode` alias also exists. Modern Node.js projects should use ESM imports.

stringify

✓ import { stringify } from 'ini'

✗ const stringify = require('ini').stringify

Primary function to convert an object to an INI string. The `encode` alias also exists. Modern Node.js projects should use ESM imports.

safe

✓ import { safe } from 'ini'

✗ const safe = require('ini').safe

Utility to escape a string for use as a key or value in an INI file.

unsafe

✓ import { unsafe } from 'ini'

✗ const unsafe = require('ini').unsafe

Utility to unescape a string previously escaped for an INI file.

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);

Debug

Known issues

breakingVersion 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.

affects: >=6.0.0

breakingVersion 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.

affects: >=5.0.0 <6.0.0

breakingVersion 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.

affects: >=3.0.0 <4.0.0

gotchaWhen 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`.

affects: >=1.0.0

gotchaThe `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`.

affects: >=4.1.0

deprecatedFor 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' })`.

affects: >=1.0.0

Errors

Common errors & fixes

The "ini" package is not compatible with your Node.js version. Requires: ^20.17.0 || >=22.9.0

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())

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)

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 })`.

Upgrade

Version history

0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/npm/ini ↗

packagehttps://www.npmjs.com/package/ini ↗