# ini

> An ini encoder/decoder for node

Latest version **7.0.0** (published 2026-05-08) · ISC license · 0 weekly downloads

## Install

```sh
npm install ini
pnpm add ini
yarn add ini
bun add ini
```

## Health

**Score 63/100 (C)** — status: active.

Positive: has types package; no vulnerabilities; has provenance; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 7.0.0 |
| Published | 2026-05-08 |
| First published | 2011-08-07 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | separate (@types/ini) |
| Module format | CommonJS |
| Node | ^22.22.2 \|\| ^24.15.0 \|\| >=26.0.0 |
| Dependencies | 0 |
| Unpacked size | 11.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 819 |
| Author | GitHub Inc. |
| Maintainers | saquibkhan, npm-cli-ops, reggi, owlstronaut |

## Links

- npm: https://www.npmjs.com/package/ini
- Repository: https://github.com/npm/ini
- Homepage: https://github.com/npm/ini#readme
- Issues: https://github.com/npm/ini/issues
- npm.io page: https://npm.io/package/ini

## Recent versions

- 7.0.0 (latest) — 2026-05-08
- 6.0.0 — 2025-10-22
- 5.0.0 — 2024-09-04
- 4.1.3 — 2024-05-22
- 4.1.2 — 2024-03-04
- 4.1.1 — 2023-05-16
- 4.1.0 — 2023-04-13
- 4.0.0 — 2023-03-21
- 3.0.1 — 2022-08-22
- 3.0.0 — 2022-04-05
- 2.0.0 — 2020-12-11
- 1.3.8 — 2020-12-11
- 1.3.7 — 2020-12-09
- 1.3.6 — 2020-12-08
- 1.3.5 — 2017-11-21
- … 14 more at https://npm.io/package/ini/versions

## README

An INI format parser & serializer.

## Note

-   Sections are treated as nested objects.

-   Section-less items are treated as globals.

## Usage

Consider an INI file such as the following:

```ini
; 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
```

You can **read**, **modify** and **write** it like so:

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

//  Read INI file as text

let text = await readFile(`./Original.ini`,{
    encoding : 'utf-8'
})

//  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
config.paths.default.array.push('fourth value')

//  Stringify data object

text = stringify(config,{ 
    section : 'section' 
})

//  Write INI file as text

await writeFile(`./Modified.ini`,text)
```

The written file will contain the following:

```ini
[section]
scope=local
[section.database]
user=dbuser
password=dbpassword
database=use_another_database
[section.paths.default]
tmpdir=/tmp
array[]=first value
array[]=second value
array[]=third value
array[]=fourth value
```

## API

### Parse

Attempts to turn the given INI string into a nested data object.

```js
// You can also use `decode`
const object = parse(`<INI Text>`) 
```

### Stringify

Encodes the given data object as an INI formatted string.

```js
// You can also use `encode`
stringify(object,{

    /**
     *  Whether to insert spaces before & after `=`
     * 
     *  Disabled by default to have better 
     *  compatibility with old picky parsers.
     */

    whitespace : false ,

    /**
     *  Whether to align the `=` character for each section.
     *  -> Also enables the `whitespace` option
     */

    align : false ,

    /**
     *  Identifier to use for global items 
     *  and to prepend to all other sections.
     */

    section ,

    /**
     *  Whether to sort all sections & their keys alphabetically.
     */

    sort : false ,

    /**
     *  Whether to insert a newline after each section header.
     * 
     *  The TOSHIBA & FlashAir parser require this format. 
     */

    newline : false ,

    /**
     *  Which platforms line-endings should be used.
     * 
     *  win32 -> CR+LF
     *  other -> LF
     * 
     *  Default is the current platform
     */

    platform ,

    /**
     *  Whether to append `[]` to array keys.
     * 
     *  Some parsers treat duplicate names by themselves as arrays
     */

    bracketedArray : true

})
```

*For backwards compatibility any string passed as the*  
*options parameter is treated as the `section` option.*

```js
stringify(object,'section')
```

### Un / Escape

Turn the given string into a safe to  
use key or value in your INI file.

```js
safe(`"unsafe string"`) // -> \"unsafe string\"
```

Or reverse the process with:

```js
unsafe(`\\"safe string\\"`) // -> "safe string"
```

---
_Source: https://npm.io/package/ini · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._