unknwon · Nov 9, 2026 · Nov 9, 2026 · Nov 9, 2026 · Nov 9, 2026 · Nov 9, 2026
diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml
@@ -1,16 +1,18 @@
 name: Go
 on:
   push:
-    branches: [main]
+    branches: [main, v2]
     paths:
       - '**.go'
       - 'go.mod'
+      - 'testdata/**'
       - '.golangci.yml'
       - '.github/workflows/go.yml'
   pull_request:
     paths:
       - '**.go'
       - 'go.mod'
+      - 'testdata/**'
       - '.golangci.yml'
       - '.github/workflows/go.yml'
 env:
@@ -37,7 +39,7 @@ jobs:
     name: Test
     strategy:
       matrix:
-        go-version: [1.26.x]
+        go-version: [1.26.x, 1.27.x]
         platform: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.platform }}
     steps:

diff --git a/README.md b/README.md
@@ -1,41 +1,92 @@
 # INI
 
-[![GoDoc](https://img.shields.io/badge/GoDoc-Reference-blue?style=for-the-badge&logo=go)](https://pkg.go.dev/github.com/go-ini/ini?tab=doc)
+[![GoDoc](https://img.shields.io/badge/GoDoc-Reference-blue?style=for-the-badge&logo=go)](https://pkg.go.dev/unknwon.dev/ini/v2?tab=doc)
 
 ![](https://avatars0.githubusercontent.com/u/10216035?v=3&s=200)
 
-Package ini provides INI file read and write functionality in Go.
+Package ini reads and writes INI files in Go.
 
 ## Features
 
-- Load from multiple data sources(file, `[]byte`, `io.Reader` and `io.ReadCloser`) with overwrites.
-- Read with recursion values.
-- Read with parent-child sections.
-- Read with auto-increment key names.
-- Read with multiple-line values.
-- Read with tons of helper methods.
-- Read and convert values to Go types.
-- Read and **WRITE** comments of sections and keys.
-- Manipulate sections, keys and comments with ease.
-- Keep sections and keys in order as you parse and save.
+- Load from files, `[]byte` and `io.Reader`, merging several sources in order.
+- Sections and keys kept in order, parent-child sections, auto-increment keys, repeated (shadow) keys, nested values, multiline values, and `%(name)s` references.
+- Typed access to values: numbers, booleans, durations, times, and lists, ranges and candidates of any of them.
+- Map files to and from structs, and `Marshal` and `Unmarshal` like `encoding/json`.
+- Write files back with their comments and order. What is written always loads back the same.
+- Parse errors that give the line and column.
+- Safe for concurrent use.
 
 ## Installation
 
-The minimum requirement of Go is **1.13**.
+The minimum requirement of Go is **1.26**.
 
 ```sh
-$ go get gopkg.in/ini.v1@latest
+go get unknwon.dev/ini/v2@latest
 ```
 
-> [!NOTE]
-> If you previously used `github.com/go-ini/ini` as the import path in your project, without updating all of your code, you can use the following command to replace the import path in your `go.mod`:
-> ```zsh
-> go mod edit -replace github.com/go-ini/ini=gopkg.in/ini.v1@latest
-> ```
+## Getting started
 
-## Getting Help
+```go
+package main
 
-- [Getting Started](https://ini.unknwon.io/docs/intro/getting_started)
+import (
+	"fmt"
+	"log"
+	"time"
+
+	"unknwon.dev/ini/v2"
+)
+
+func main() {
+	f, err := ini.Load("app.ini")
+	if err != nil {
+		log.Fatal(err) // e.g., "line 3, column 1: key-value delimiter not found: broken line"
+	}
+
+	server := f.Section("server")
+	port := server.Key("port").MustInt(8080)
+	timeout := server.Key("timeout").MustDuration(30 * time.Second)
+	fmt.Println(port, timeout)
+
+	server.Key("port").SetValue("9090")
+	if err := f.SaveTo("app.ini"); err != nil {
+		log.Fatal(err)
+	}
+}
+```
+
+Options change the syntax that is accepted, such as `ini.Load("app.ini", ini.AllowShadows(true), ini.IgnoreInlineComment(true))`. The [package documentation](https://pkg.go.dev/unknwon.dev/ini/v2) has examples of struct mapping, typed lists and write options.
+
+## Performance
+
+v2 loads files up to 31 times faster than v1, with a third to a fifth of the allocations:
+
+| Operation | v1.67.3 | v2 | Allocations, v1 → v2 |
+|---|---|---|---|
+| Load 10,000 keys in one section | 137 ms | 4.4 ms (31× faster) | 50.2k → 10.1k |
+| Load 10,000 keys in 1,000 sections | 8.2 ms | 3.2 ms (2.5× faster) | 58.1k → 18.1k |
+| Load 10,000 keys, mixed syntax | 101 ms | 3.9 ms (26× faster) | 57.6k → 18.8k |
+| Write 10,000 keys | 2.2–4.3 ms | 4.3–7.4 ms (1.7–2.0× slower) | 3.0k–20.0k → 13.0k–30.0k |
+| `MapTo` a 13-field struct | 3.8 µs | 4.5 µs | 44 → 48 |
+| `ReflectFrom` the same struct | 13.9 µs | 11.8 µs | 132 → 118 |
+| Read one key | 60 ns | 71 ns, or 36 ns with `Locking(false)` | 0 → 0 |
+
+- **Load** is linear in the number of keys. v1 compared each new key with every key before it in its section, so a large section took quadratic time.
+- **Write** is slower because it checks that every line it writes reads back as the same value. v1 could write files that loaded differently.
+- **Reads** take the file's read lock so that they are safe while other goroutines change the file. v1 read without it.
+
+Measured with Go 1.26.10 on a 4-core Intel Xeon at 2.60 GHz, as the median of 8 runs.
+
+## Migrating from v1
+
+Without options, v2 parses every input exactly as v1 does. The API changed: the import path is `unknwon.dev/ini/v2`, options are functions, package-level settings became options, and typed list methods became generic functions. A few behaviors changed in ways the compiler can't catch, such as `Must*` methods no longer storing their default in the file.
+
+The [migration guide](docs/migrate-v1-to-v2.md) lists every change.
+
+## Getting help
+
+- [Package documentation and examples](https://pkg.go.dev/unknwon.dev/ini/v2)
+- [Documentation site](https://ini.unknwon.io/docs/intro/getting_started), which still describes v1
 
 ## License
 

diff --git a/bench_test.go b/bench_test.go
@@ -1,26 +1,17 @@
-// Copyright 2017 Unknwon
-//
-// Licensed under the Apache License, Version 2.0 (the "License"): you may
-// not use this file except in compliance with the License. You may obtain
-// a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-// License for the specific language governing permissions and limitations
-// under the License.
-
 package ini
 
 import (
 	"testing"
+
+	"github.com/stretchr/testify/require"
 )
 
 func newTestFile(block bool) *File {
-	c, _ := Load([]byte(confData))
-	c.BlockMode = block
+	var opts []LoadOption
+	if !block {
+		opts = append(opts, Locking(false))
+	}
+	c, _ := Load([]byte(confData), opts...)
 	return c
 }
 
@@ -117,9 +108,7 @@ func Benchmark_Key_SetValue_VisSection(b *testing.B) {
 
 func Benchmark_Key_Strings_LargeArray(b *testing.B) {
 	c, err := Load("testdata/large_array.ini")
-	if err != nil {
-		b.Fatal(err)
-	}
+	require.NoError(b, err)
 	key := c.Section("").Key("ARRAY")
 	b.ReportAllocs()
 	b.ResetTimer()

diff --git a/codecov.yml b/codecov.yml
diff --git a/data_source.go b/data_source.go
@@ -1,17 +1,3 @@
-// Copyright 2019 Unknwon
-//
-// Licensed under the Apache License, Version 2.0 (the "License"): you may
-// not use this file except in compliance with the License. You may obtain
-// a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-// License for the specific language governing permissions and limitations
-// under the License.
-
 package ini
 
 import (
@@ -50,25 +36,38 @@ func (s *sourceData) ReadCloser() (io.ReadCloser, error) {
 	return io.NopCloser(bytes.NewReader(s.data)), nil
 }
 
-// sourceReadCloser represents an input stream with Close method.
+// sourceReadCloser represents an input stream with Close method. A stream
+// can be read only once, so its data is kept for reloading.
 type sourceReadCloser struct {
 	reader io.ReadCloser
+	data   []byte
+	err    error
 }
 
 func (s *sourceReadCloser) ReadCloser() (io.ReadCloser, error) {
-	return s.reader, nil
+	if s.reader != nil {
+		s.data, s.err = io.ReadAll(s.reader)
+		if err := s.reader.Close(); s.err == nil {
+			s.err = err
+		}
+		s.reader = nil
+	}
+	if s.err != nil {
+		return nil, s.err
+	}
+	return io.NopCloser(bytes.NewReader(s.data)), nil
 }
 
-func parseDataSource(source interface{}) (dataSource, error) {
+func newDataSource(source any) (dataSource, error) {
 	switch s := source.(type) {
 	case string:
 		return sourceFile{s}, nil
 	case []byte:
 		return &sourceData{s}, nil
 	case io.ReadCloser:
-		return &sourceReadCloser{s}, nil
+		return &sourceReadCloser{reader: s}, nil
 	case io.Reader:
-		return &sourceReadCloser{io.NopCloser(s)}, nil
+		return &sourceReadCloser{reader: io.NopCloser(s)}, nil
 	default:
 		return nil, fmt.Errorf("error parsing data source: unknown type %q", s)
 	}

diff --git a/deprecated.go b/deprecated.go