Format file INI digunakan untuk menyimpan pengaturan aplikasi sejak masa-masa awal Windows, dan masih aktif digunakan di proyek Python, konfigurasi PHP, MySQL, Git, dan puluhan alat lainnya. Membuatnya dengan benar membutuhkan pemahaman beberapa aturan sintaks, mengetahui di mana parser berbeda dalam perilakunya, dan memilih format yang tepat untuk kasus penggunaan Anda. Panduan ini mencakup semuanya — dari baris pertama hingga validasi.
Apa itu file INI?
File INI adalah file konfigurasi teks biasa yang menyimpan pengaturan sebagai pasangan kunci-nilai, opsional dikelompokkan ke dalam seksi bernama. Namanya berasal dari "initialisation" (inisialisasi) — file INI dulu dipakai untuk menginisialisasi aplikasi Windows dengan pengaturannya sebelum Windows Registry ada. Format ini tidak pernah punya spesifikasi formal, tetapi standar de-facto muncul dari penggunaan yang luas.
Di mana file INI digunakan saat ini
- Pengemasan Python — `setup.cfg`, `tox.ini`, `pytest.ini`, `mypy.ini`, `.flake8`
- Runtime PHP — `php.ini` mengatur pengaturan interpreter PHP secara global
- MySQL / MariaDB — `my.ini` (Windows) dan `my.cnf` (Unix) mengonfigurasi server basis data
- Git — `.gitconfig` dan `.git/config` menggunakan format mirip INI untuk pengaturan repositori dan pengguna
- Wine — `wine.inf` mengonfigurasi lapisan kompatibilitas Windows di Linux dan macOS
- Aplikasi Windows — ribuan aplikasi desktop lama dan modern menyimpan preferensi di file `.ini` di folder AppData
INI vs Windows Registry
Microsoft memindahkan pengaturan aplikasi Windows ke Registry pada awal 1990-an demi kinerja dan manajemen tersentralisasi. Namun banyak pengembang tetap memilih file INI karena portabilitas — file INI dapat diperiksa dan diedit dengan editor teks apa pun, di-commit ke kontrol versi, dan disalin antar mesin tanpa alat ekspor/impor apa pun. Registry tidak bisa.
Note
Aturan sintaks file INI
Meskipun tanpa spesifikasi formal, sintaks INI mengikuti konvensi yang konsisten di hampir semua parser. Inilah aturan yang dapat Anda andalkan apa pun yang membaca file Anda.
File INI adalah format konfigurasi yang paling sederhana: seksi dalam kurung siku, pasangan kunci-nilai di bawahnya, dan titik koma untuk komentar. Selebihnya spesifik parser.
Aturan universal
- Satu pasangan kunci-nilai per baris — `key = value` atau `key=value`; spasi di sekitar `=` opsional tetapi spasi yang konsisten lebih mudah dibaca
- Judul seksi — `[NamaSeksi]` sendirian pada barisnya; tanpa konten setelah kurung penutup
- Baris komentar — mulai dengan `;` untuk kompatibilitas maksimal; `#` didukung sebagian parser (`configparser` Python, alat Linux) tetapi tidak oleh API native Windows
- Baris kosong — diabaikan semua parser; gunakan bebas untuk memisahkan grup logis di dalam sebuah seksi
- Tanpa penyarangan — INI datar: seksi berisi pasangan kunci-nilai, bukan seksi lain
- Nilai string — semua nilai adalah string kecuali parser mengonversinya; `count = 5` adalah string "5" bagi kebanyakan parser
Apa yang dilihat parser
Parser membangun peta dua tingkat: nama seksi → kunci → nilai. Jika file tidak punya judul seksi, nilai berada di seksi implisit "default" — `configparser` Python menyebutnya `DEFAULT`. Apakah parser menggabungkan seksi default dengan seksi bernama bervariasi. Kunci dan nama seksi hampir universally diperlakukan peka huruf besar-kecil secara tidak langsung (case-insensitive) secara konvensi, meskipun tidak dijamin semua implementasi.
Tip
Membuat file INI pertama Anda
Membuat file INI hanya perlu kurang dari lima langkah. Satu-satunya alat yang dibutuhkan adalah editor teks biasa — editor apa pun yang menyimpan sebagai UTF-8 atau ASCII tanpa tanda urutan byte (BOM) berfungsi dengan benar.
Buat file teks baru dengan ekstensi .ini
Buka editor teks Anda (VS Code, Notepad, nano, vim — semuanya bisa) dan buat file baru. Simpan dengan ekstensi `.ini` sebelum menulis konten agar editor menerapkan penyorotan sintaks INI jika tersedia. Di Windows, pastikan "Save as type" diatur ke "All files" di Notepad agar file tidak tersimpan sebagai `config.ini.txt` alih-alih `config.ini`.
Tambahkan judul seksi pertama Anda
Tulis nama seksi pertama Anda dalam kurung siku pada baris tersendiri. Nama seksi adalah label deskriptif — `[database]`, `[server]`, `[logging]` adalah pilihan konvensional. Anda juga bisa langsung menulis pasangan kunci-nilai tanpa judul seksi apa pun jika konfigurasi Anda cukup sederhana sehingga tidak perlu pengelompokan.
Tambahkan pasangan kunci-nilai di bawah setiap seksi
Di bawah judul seksi, tulis satu pasangan `key = value` per baris. Kunci sebaiknya huruf kecil dengan garis bawah (snake_case) demi kompatibilitas lintas parser maksimal. Nilai boleh memuat spasi, tanda baca, dan sebagian besar karakter khusus. Jangan apit nilai dengan tanda kutip — kutip dianggap karakter literal oleh kebanyakan parser, bukan pembatas string.
Tambahkan komentar untuk mendokumentasikan nilai yang tidak jelas
Mulailah baris komentar dengan titik koma (`;`). Komentar harus di baris khususnya sendiri — menempatkan komentar setelah nilai di baris yang sama (`host = localhost ; primary DB`) tidak didukung andal oleh semua parser dan bisa menyertakan teks komentar ke dalam nilai. Jika Anda butuh catatan sebaris, letakkan di baris sebelumnya sebagai komentar tersendiri.
Validasi file yang selesai
Tempel file INI yang sudah jadi ke Validator INI untuk memeriksa kesalahan sintaks, nama seksi duplikat, dan kepatuhan format. Validator melaporkan masalah dengan nomor baris sehingga Anda bisa memperbaikinya sebelum file masuk produksi. Jika perlu format yang konsisten, jalankan dulu lewat Formatter INI.
Validator INI
Periksa file INI atau CFG apa pun untuk kesalahan sintaks, seksi duplikat, dan kepatuhan format — laporan kesalahan tingkat baris tanpa perlu unggahan.
Seksi, kunci, dan nilai secara mendalam
Tiga elemen struktural file INI — seksi, kunci, dan nilai — memiliki aturan dan kasus tepi yang layak dipahami sebelum menulis konfigurasi yang akan dibaca parser orang lain.
Konvensi penamaan seksi
Nama seksi berada dalam kurung siku dan muncul pada barisnya sendiri. Bisa berisi huruf, angka, spasi, dan kebanyakan tanda baca — tetapi spasi pada nama seksi kurang didukung sebagian parser dan sebaiknya dihindari. Gunakan `[DatabaseConfig]` atau `[database_config]` daripada `[database config]`. Nama seksi duplikat digabungkan atau memicu kesalahan tergantung parser — perlakukan sebagai larangan dan validasi dengan Validator INI untuk menangkap duplikat.
Aturan penamaan kunci
Kunci tidak boleh memuat tanda `=` atau baris baru. Lebih dari itu, konvensinya bervariasi, tetapi praktik teraman adalah hanya memakai huruf kecil, angka, dan garis bawah — aturan yang sama dengan nama variabel Python. Hindari tanda hubung pada kunci jika berencana membacanya di Python dengan `configparser`, karena Python mengembalikan kunci apa adanya dan kunci bertanda hubung tidak bisa diakses sebagai atribut.
Jenis nilai dan nilai multibaris
Semua nilai dalam file INI adalah string kecuali parser Anda mengonversinya secara eksplisit. `enabled = true` adalah string "true" — kode Anda harus mengonversinya menjadi boolean. `configparser` Python menyediakan metode `getboolean()`, `getint()`, dan `getfloat()` untuk tujuan ini. Nilai multibaris didukung sebagian parser (`configparser` Python memperlakukan baris dengan spasi awal sebagai kelanjutan nilai sebelumnya) tetapi tidak semua — cek dokumentasi parser Anda sebelum bergantung padanya.
Seksi DEFAULT
`configparser` Python memperlakukan seksi bernama `[DEFAULT]` (tidak peka huruf besar-kecil) sebagai seksi fallback khusus. Kunci apa pun yang didefinisikan di `[DEFAULT]` tersedia di semua seksi lain sebagai fallback — jika sebuah seksi tidak mendefinisikan kunci, nilai dari `[DEFAULT]` yang dikembalikan. Ini perilaku khusus Python yang tidak ditemukan di kebanyakan parser lain. Jika Anda menulis file INI khusus untuk Python, `[DEFAULT]` adalah cara praktis mendefinisikan nilai bersama tanpa mengulanginya di setiap seksi.
Warning
Membaca file INI dalam kode
Sebagian besar bahasa menyediakan parser bawaan atau pustaka standar untuk file INI. Berikut pendekatan standar untuk lingkungan yang paling umum.
Python: configparser
Modul `configparser` Python adalah cara standar membaca file INI di Python. Impor modulnya, buat instansi `ConfigParser()`, panggil `.read()` dengan nama file Anda, dan akses nilai dengan `config["NamaSeksi"]["kunci"]` atau `config.get("NamaSeksi", "kunci")`. Metode `.get()` menerima argumen `fallback` yang mengembalikan nilai bawaan saat kunci hilang — berguna untuk nilai konfigurasi opsional. Gunakan `getboolean()`, `getint()`, dan `getfloat()` untuk nilai bertipe daripada meng-cast string secara manual.
PHP: parse_ini_file()
PHP menyediakan `parse_ini_file($filename, $process_sections)` sebagai fungsi bawaan. Dengan `$process_sections = true`, fungsi mengembalikan array asosiatif bersarang yang diorganisir berdasarkan nama seksi. Dengan `false`, ia mengembalikan array datar dengan semua kunci digabung. Parser PHP ketat terhadap karakter khusus tertentu pada nilai tanpa tanda kutip — nilai yang memuat =, kurung kurawal pembuka/penutup, |, &, ~, !, [, ] perlu diberi tanda kutip di file INI agar terurai dengan benar.
Node.js dan lingkungan lain
Node.js tidak punya parser INI bawaan, tetapi paket npm `ini` (lisensi MIT) menyediakan antarmuka standar `parse()` dan `stringify()`. Untuk Java, pustaka `org.ini4j` adalah pilihan standar. Untuk Go, paket `gopkg.in/ini.v1` adalah opsi yang paling banyak dipakai. Dalam tiap kasus, pustaka menangani struktur dua tingkat seksi/kunci yang sama — bentuk API berbeda tetapi format dasarnya identik.
Tip
INI vs TOML vs YAML
INI tidak selalu format konfigurasi yang tepat. Memahami di mana ia cocok — dan di mana TOML atau YAML lebih baik — membantu Anda mengambil keputusan yang benar untuk proyek baru.
| Fitur | INI | TOML | YAML |
|---|---|---|---|
| Kompleksitas sintaks | Minimal | Moderat | Tinggi |
| Dukungan tipe native | ✗ Hanya string | ✓ Tipe lengkap | ✓ Tipe lengkap |
| Struktur bersarang | ✗ Maks. dua tingkat | ✓ Tabel inline | ✓ Kedalaman tak terbatas |
| Array / daftar | ✗ Tidak standar | ✓ Array native | ✓ Sekuens blok |
| Komentar | ✓ ; dan # | ✓ Hanya # | ✓ Hanya # |
| Spesifikasi formal | ✗ Tanpa spesifikasi resmi | ✓ Spesifikasi TOML | ✓ Spesifikasi YAML 1.2 |
| Paling cocok untuk | Konfigurasi aplikasi sederhana | Rust, paket Python | DevOps, Kubernetes |
| Keterbacaan | Sangat tinggi | Tinggi | Sedang (sensitif indentasi) |
Kapan menggunakan INI
INI adalah pilihan yang tepat ketika konfigurasi Anda sedalam dua tingkat (seksi dan pasangan kunci-nilai datar), ketika parser target sudah mengharapkan format INI (PHP, ekosistem Python, MySQL, Git), dan ketika Anda menginginkan format sesederhana mungkin yang bisa dibaca pengembang mana pun tanpa pengetahuan awal. Tidak cocok untuk konfigurasi yang membutuhkan array, objek bersarang, atau data bertipe.
Kapan menggunakan TOML atau YAML sebagai gantinya
Pilih TOML ketika konfigurasi Anda butuh nilai bertipe, array, atau tabel inline dan Anda menginginkan spesifikasi ketat dengan penguraian yang dapat diprediksi. TOML adalah format untuk `pyproject.toml`, `Cargo.toml`, dan berkas konfigurasi Hugo. Pilih YAML ketika Anda butuh struktur bersarang mendalam atau bekerja di ekosistem yang sudah menjadikan YAML standar — Kubernetes, GitHub Actions, Docker Compose, dan Ansible semuanya lingkungan yang mengutamakan YAML.
Key takeaways
- File INI adalah file konfigurasi teks biasa dengan seksi bernama dalam `[kurung siku]` dan pasangan `key = value` di bawahnya.
- Gunakan `;` untuk komentar — bukan `#` — demi kompatibilitas maksimal lintas Windows, PHP, Python, dan parser INI lainnya.
- Simpan file INI sebagai UTF-8 tanpa BOM; hindari komentar sebaris (setelah nilai di baris yang sama) karena tidak didukung secara universal.
- Semua nilai INI adalah string kecuali parser Anda mengonversinya secara eksplisit — gunakan `getboolean()`, `getint()`, dan `getfloat()` di Python.
- Jangan pernah menyimpan kata sandi atau kunci API dalam file INI yang di-commit ke kontrol versi — gunakan variabel lingkungan untuk nilai sensitif.
- Validasi dengan Validator INI sebelum penerapan untuk menangkap kesalahan sintaks, seksi duplikat, dan masalah format.
- Gunakan TOML untuk konfigurasi yang butuh nilai bertipe dan array; gunakan YAML untuk struktur bersarang mendalam — INI hanya ideal untuk konfigurasi sederhana dua tingkat.
Komentar dan pengodean
Komentar dan pengodean karakter adalah dua aspek file INI yang paling mungkin menimbulkan masalah senyap ketika file dibagikan lintas alat, sistem operasi, atau bahasa pemrograman yang berbeda.
Karakter komentar: ; vs #
Titik koma (`;`) adalah karakter komentar yang didukung secara universal — bekerja di `configparser` Python, API native Windows, `parse_ini_file()` PHP, MySQL, dan praktis semua parser INI lainnya. Tanda pagar (`#`) didukung `configparser` Python dan kebanyakan parser berbasis Linux tetapi tidak didukung `GetPrivateProfileString()` Windows. Jika file INI Anda hanya akan dibaca Python, salah satu karakter aman digunakan. Untuk file lintas platform, gunakan secara eksklusif `;`.
Pengodean karakter: UTF-8 vs Windows-1252
Simpan file INI sebagai UTF-8 tanpa BOM untuk alat modern. BOM (byte order mark, karakter tak terlihat `\uFEFF` di awal beberapa file UTF-8 yang disimpan alat Windows) menimbulkan masalah pada parser yang menganggapnya bagian dari nama kunci pertama. `configparser` Python menangani UTF-8 secara native sejak Python 3. Jika Anda menulis file INI untuk aplikasi Windows lama yang mengharapkan pengodean Windows-1252, sesuaikan dengan yang diharapkan aplikasi — campuran pengodean adalah sumber umum kerusakan karakter pada nilai.
Akhiran baris
File INI bekerja dengan akhiran baris Windows (CRLF, `\r\n`) maupun Unix (LF, `\n`). Gunakan konvensi akhiran baris platform target Anda. Jika Anda mengedit file INI di Windows untuk penyebaran di Linux, atur editor teks menyimpan dengan akhiran baris LF agar karakter carriage return tidak muncul dalam nilai pada parser Linux. Formatter INI menormalkan akhiran baris dan spasi dalam sekali jalan.