{"id":13411123,"url":"https://github.com/knadh/koanf","last_synced_at":"2026-04-01T21:12:05.727Z","repository":{"id":37631625,"uuid":"192480120","full_name":"knadh/koanf","owner":"knadh","description":"Simple, extremely lightweight, extensible, configuration management library for Go. Supports JSON, TOML, YAML, env, command line, file, S3 etc. Alternative to viper.","archived":false,"fork":false,"pushed_at":"2026-03-31T18:57:43.000Z","size":726,"stargazers_count":3948,"open_issues_count":3,"forks_count":185,"subscribers_count":23,"default_branch":"master","last_synced_at":"2026-03-31T20:41:18.512Z","etag":null,"topics":["config","config-loader","configuration","configuration-file","configuration-management","etcd-client","go","golang","golang-package","s3-bucket","toml","viper","yaml"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knadh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-06-18T06:34:05.000Z","updated_at":"2026-03-31T20:33:29.000Z","dependencies_parsed_at":"2024-02-02T13:59:54.722Z","dependency_job_id":"7ff39484-e8a5-4fde-abeb-3ea7ee5d1fb9","html_url":"https://github.com/knadh/koanf","commit_stats":{"total_commits":239,"total_committers":49,"mean_commits":4.877551020408164,"dds":0.5774058577405858,"last_synced_commit":"ec1d17c8f97ebc12433d4336492c937f1dbb4331"},"previous_names":[],"tags_count":159,"template":false,"template_full_name":null,"purl":"pkg:github/knadh/koanf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knadh%2Fkoanf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knadh%2Fkoanf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knadh%2Fkoanf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knadh%2Fkoanf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knadh","download_url":"https://codeload.github.com/knadh/koanf/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knadh%2Fkoanf/sbom","scorecard":{"id":564267,"data":{"date":"2025-08-11","repo":{"name":"github.com/knadh/koanf","commit":"d66cde5a8f91502477f192d4188d6a34d0b3052d"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":5.1,"checks":[{"name":"Maintained","score":10,"reason":"13 commit(s) and 6 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/test.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":5,"reason":"Found 7/13 approved changesets -- score normalized to 5","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/knadh/koanf/test.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/knadh/koanf/test.yml/master?enable=pin","Info:   0 out of   2 GitHub-owned GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 25 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":8,"reason":"2 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2025-3787 / GHSA-fv92-fjc5-jj9h","Warn: Project is vulnerable to: GO-2024-2631 / GHSA-c5q2-7r4c-mv6g"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-20T14:31:58.628Z","repository_id":37631625,"created_at":"2025-08-20T14:31:58.628Z","updated_at":"2025-08-20T14:31:58.628Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292083,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["config","config-loader","configuration","configuration-file","configuration-management","etcd-client","go","golang","golang-package","s3-bucket","toml","viper","yaml"],"created_at":"2024-07-30T20:01:11.572Z","updated_at":"2026-04-01T21:12:05.682Z","avatar_url":"https://github.com/knadh.png","language":"Go","readme":"\u003ca href=\"https://zerodha.tech\"\u003e\u003cimg src=\"https://zerodha.tech/static/images/github-badge.svg\" align=\"right\" /\u003e\u003c/a\u003e\n\n![koanf](https://user-images.githubusercontent.com/547147/72681838-6981dd00-3aed-11ea-8f5d-310816c70c08.png)\n\n**koanf** is a library for reading configuration from different sources in different formats in Go applications. It is a cleaner, lighter [alternative to spf13/viper](#alternative-to-viper) with better abstractions and extensibility and far fewer dependencies.\n\nkoanf v2 has modules (Providers) for reading configuration from a variety of sources such as files, command line flags, environment variables, Vault, and S3 and for parsing (Parsers) formats such as JSON, YAML, TOML, HUML, Hashicorp HCL. It is easy to plug in custom parsers and providers.\n\nAll external dependencies in providers and parsers are detached from the core and can be installed separately as necessary.\n\n[![Run Tests](https://github.com/knadh/koanf/actions/workflows/test.yml/badge.svg)](https://github.com/knadh/koanf/actions/workflows/test.yml) [![GoDoc](https://pkg.go.dev/badge/github.com/knadh/koanf?utm_source=godoc)](https://pkg.go.dev/github.com/knadh/koanf/v2) \n\n### Installation\n\n```shell\n# Install the core.\ngo get -u github.com/knadh/koanf/v2\n\n# Install the necessary Provider(s).\n# Available: file, env/v2, posflag, basicflag, confmap, rawbytes,\n#            structs, fs, s3, appconfig/v2, consul/v2, etcd/v2, vault/v2, parameterstore/v2\n# eg: go get -u github.com/knadh/koanf/providers/s3\n# eg: go get -u github.com/knadh/koanf/providers/consul/v2\n\ngo get -u github.com/knadh/koanf/providers/file\n\n\n# Install the necessary Parser(s).\n# Available: toml, toml/v2, json, yaml, huml, dotenv, hcl, hjson, nestedtext\n# go get -u github.com/knadh/koanf/parsers/$parser\n\ngo get -u github.com/knadh/koanf/parsers/toml\n```\n\n[See the list](#api) of all bundled Providers and Parsers.\n\n### Contents\n\n- [Concepts](#concepts)\n- [Reading config from files](#reading-config-from-files)\n- [Watching file for changes](#watching-file-for-changes)\n- [Reading from command line](#reading-from-command-line)\n- [Reading environment variables](#reading-environment-variables)\n- [Reading from an S3 bucket](#reading-from-an-s3-bucket)\n- [Reading raw bytes](#reading-raw-bytes)\n- [Reading from maps and structs](#reading-from-nested-maps)\n- [Unmarshalling and marshalling](#unmarshalling-and-marshalling)\n- [Order of merge and key case sensitivity](#order-of-merge-and-key-case-sensitivity)\n- [Custom Providers and Parsers](#custom-providers-and-parsers)\n- [Custom merge strategies](#custom-merge-strategies)\n- [List of installable Providers and Parsers](#api)\n\n### Concepts\n\n- `koanf.Provider` is a generic interface that provides configuration, for example, from files, environment variables, HTTP sources, or anywhere. The configuration can either be raw bytes that a parser can parse, or it can be a nested `map[string]any` that can be directly loaded.\n- `koanf.Parser` is a generic interface that takes raw bytes, parses, and returns a nested `map[string]any`. For example, JSON and YAML parsers.\n- Once loaded into koanf, configuration are values queried by a delimited key path syntax. eg: `app.server.port`. Any delimiter can be chosen.\n- Configuration from multiple sources can be loaded and merged into a koanf instance, for example, load from a file first and override certain values with flags from the command line.\n\nWith these two interface implementations, koanf can obtain configuration in any format from any source, parse it, and make it available to an application.\n\n### Reading config from files\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/knadh/koanf/v2\"\n\t\"github.com/knadh/koanf/parsers/json\"\n\t\"github.com/knadh/koanf/parsers/yaml\"\n\t\"github.com/knadh/koanf/providers/file\"\n)\n\n// Global koanf instance. Use \".\" as the key path delimiter. This can be \"/\" or any character.\nvar k = koanf.New(\".\")\n\nfunc main() {\n\t// Load JSON config.\n\tif err := k.Load(file.Provider(\"mock/mock.json\"), json.Parser()); err != nil {\n\t\tlog.Fatalf(\"error loading config: %v\", err)\n\t}\n\n\t// Load YAML config and merge into the previously loaded config (because we can).\n\tk.Load(file.Provider(\"mock/mock.yml\"), yaml.Parser())\n\n\tfmt.Println(\"parent's name is = \", k.String(\"parent1.name\"))\n\tfmt.Println(\"parent's ID is = \", k.Int(\"parent1.id\"))\n}\n\n```\n\n### Watching file for changes\nSome providers expose a `Watch()` method that makes the provider watch for changes\nin configuration and trigger a callback to reload the configuration.\nThis is not goroutine safe if there are concurrent `*Get()` calls happening on the\nkoanf object while it is doing a `Load()`. Such scenarios will need mutex locking.\n\n`file, appconfig, vault, consul` providers have a `Watch()` method.\n\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/knadh/koanf/v2\"\n\t\"github.com/knadh/koanf/parsers/json\"\n\t\"github.com/knadh/koanf/parsers/yaml\"\n\t\"github.com/knadh/koanf/providers/file\"\n)\n\n// Global koanf instance. Use \".\" as the key path delimiter. This can be \"/\" or any character.\nvar k = koanf.New(\".\")\n\nfunc main() {\n\t// Load JSON config.\n\tf := file.Provider(\"mock/mock.json\")\n\tif err := k.Load(f, json.Parser()); err != nil {\n\t\tlog.Fatalf(\"error loading config: %v\", err)\n\t}\n\n\t// Load YAML config and merge into the previously loaded config (because we can).\n\tk.Load(file.Provider(\"mock/mock.yml\"), yaml.Parser())\n\n\tfmt.Println(\"parent's name is = \", k.String(\"parent1.name\"))\n\tfmt.Println(\"parent's ID is = \", k.Int(\"parent1.id\"))\n\n\t// Watch the file and get a callback on change. The callback can do whatever,\n\t// like re-load the configuration.\n\t// File provider always returns a nil `event`.\n\tf.Watch(func(event any, err error) {\n\t\tif err != nil {\n\t\t\tlog.Printf(\"watch error: %v\", err)\n\t\t\treturn\n\t\t}\n\n\t\t// Throw away the old config and load a fresh copy.\n\t\tlog.Println(\"config changed. Reloading ...\")\n\t\tk = koanf.New(\".\")\n\t\tk.Load(f, json.Parser())\n\t\tk.Print()\n\t})\n\n\t// To stop a file watcher, call:\n\t// f.Unwatch()\n\n\t// Block forever (and manually make a change to mock/mock.json) to\n\t// reload the config.\n\tlog.Println(\"waiting forever. Try making a change to mock/mock.json to live reload\")\n\t\u003c-make(chan bool)\n}\n```\n\n\n### Reading from command line\n\nThe following example shows the use of `posflag.Provider`, a wrapper over the [spf13/pflag](https://github.com/spf13/pflag) library, an advanced commandline lib. For Go's built in `flag` package, use `basicflag.Provider`.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\t\"github.com/knadh/koanf/v2\"\n\t\"github.com/knadh/koanf/parsers/toml\"\n\n\t// TOML version 2 is available at:\n\t// \"github.com/knadh/koanf/parsers/toml/v2\"\n\n\t\"github.com/knadh/koanf/providers/file\"\n\t\"github.com/knadh/koanf/providers/posflag\"\n\tflag \"github.com/spf13/pflag\"\n)\n\n// Global koanf instance. Use \".\" as the key path delimiter. This can be \"/\" or any character.\nvar k = koanf.New(\".\")\n\nfunc main() {\n\t// Use the POSIX compliant pflag lib instead of Go's flag lib.\n\tf := flag.NewFlagSet(\"config\", flag.ContinueOnError)\n\tf.Usage = func() {\n\t\tfmt.Println(f.FlagUsages())\n\t\tos.Exit(0)\n\t}\n\t// Path to one or more config files to load into koanf along with some config params.\n\tf.StringSlice(\"conf\", []string{\"mock/mock.toml\"}, \"path to one or more .toml config files\")\n\tf.String(\"time\", \"2020-01-01\", \"a time string\")\n\tf.String(\"type\", \"xxx\", \"type of the app\")\n\tf.Parse(os.Args[1:])\n\n\t// Load the config files provided in the commandline.\n\tcFiles, _ := f.GetStringSlice(\"conf\")\n\tfor _, c := range cFiles {\n\t\tif err := k.Load(file.Provider(c), toml.Parser()); err != nil {\n\t\t\tlog.Fatalf(\"error loading file: %v\", err)\n\t\t}\n\t}\n\n\t// \"time\" and \"type\" may have been loaded from the config file, but\n\t// they can still be overridden with the values from the command line.\n\t// The bundled posflag.Provider takes a flagset from the spf13/pflag lib.\n\t// Passing the Koanf instance to posflag helps it deal with default command\n\t// line flag values that are not present in conf maps from previously loaded\n\t// providers.\n\tif err := k.Load(posflag.Provider(f, \".\", k), nil); err != nil {\n\t\tlog.Fatalf(\"error loading config: %v\", err)\n\t}\n\n\tfmt.Println(\"time is = \", k.String(\"time\"))\n}\n```\n\n### Reading environment variables\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\t\"strings\"\n\n\t\"github.com/knadh/koanf/v2\"\n\t\"github.com/knadh/koanf/parsers/json\"\n\t\"github.com/knadh/koanf/providers/env/v2\"\n\t\"github.com/knadh/koanf/providers/file\"\n)\n\n// Global koanf instance. Use . as the key path delimiter. This can be / or anything.\nvar k = koanf.New(\".\")\n\nfunc main() {\n\t// Load JSON config.\n\tif err := k.Load(file.Provider(\"mock/mock.json\"), json.Parser()); err != nil {\n\t\tlog.Fatalf(\"error loading config: %v\", err)\n\t}\n\n\t// Load only environment variables with prefix \"MYVAR_\" and merge into config.\n\t// Transform var names by:\n\t// 1. Converting to lowercase\n\t// 2. Removing \"MYVAR_\" prefix  \n\t// 3. Replacing \"_\" with \".\" to representing nesting using the . delimiter.\n\t// Example: MYVAR_PARENT1_CHILD1_NAME becomes \"parent1.child1.name\"\n\tk.Load(env.Provider(\".\", env.Opt{\n\t\tPrefix: \"MYVAR_\",\n\t\tTransformFunc: func(k, v string) (string, any) {\n\t\t\t// Transform the key.\n\t\t\tk = strings.ReplaceAll(strings.ToLower(strings.TrimPrefix(k, \"MYVAR_\")), \"_\", \".\")\n\n\t\t\t// Transform the value into slices, if they contain spaces.\n\t\t\t// Eg: MYVAR_TAGS=\"foo bar baz\" -\u003e tags: [\"foo\", \"bar\", \"baz\"]\n\t\t\t// This is to demonstrate that string values can be transformed to any type\n\t\t\t// where necessary.\n\t\t\tif strings.Contains(v, \" \") {\n\t\t\t\treturn k, strings.Split(v, \" \")\n\t\t\t}\n\n\t\t\treturn k, v\n\t\t},\n\t}), nil)\n\n\tfmt.Println(\"name is =\", k.String(\"parent1.child1.name\"))\n\tfmt.Println(\"time is =\", k.Time(\"time\", time.DateOnly))\n\tfmt.Println(\"ids are =\", k.Strings(\"parent1.child1.grandchild1.ids\"))\n}\n```\n\n### Reading from an S3 bucket\n\n```go\n// Load JSON config from s3.\nif err := k.Load(s3.Provider(s3.Config{\n\tAccessKey: os.Getenv(\"AWS_S3_ACCESS_KEY\"),\n\tSecretKey: os.Getenv(\"AWS_S3_SECRET_KEY\"),\n\tRegion:    os.Getenv(\"AWS_S3_REGION\"),\n\tBucket:    os.Getenv(\"AWS_S3_BUCKET\"),\n\tObjectKey: \"dir/config.json\",\n}), json.Parser()); err != nil {\n\tlog.Fatalf(\"error loading config: %v\", err)\n}\n```\n\n### Reading raw bytes\n\nThe bundled `rawbytes` Provider can be used to read arbitrary bytes from a source, like a database or an HTTP call.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/knadh/koanf/v2\"\n\t\"github.com/knadh/koanf/parsers/json\"\n\t\"github.com/knadh/koanf/providers/rawbytes\"\n)\n\n// Global koanf instance. Use . as the key path delimiter. This can be / or anything.\nvar k = koanf.New(\".\")\n\nfunc main() {\n\tb := []byte(`{\"type\": \"rawbytes\", \"parent1\": {\"child1\": {\"type\": \"rawbytes\"}}}`)\n\tk.Load(rawbytes.Provider(b), json.Parser())\n\tfmt.Println(\"type is = \", k.String(\"parent1.child1.type\"))\n}\n```\n\n### Unmarshalling and marshalling\n`Parser`s can be used to unmarshal and scan the values in a Koanf instance into a struct based on the field tags, and to marshal a Koanf instance back into serialized bytes, for example to JSON or YAML files\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/knadh/koanf/v2\"\n\t\"github.com/knadh/koanf/parsers/json\"\n\t\"github.com/knadh/koanf/providers/file\"\n)\n\n// Global koanf instance. Use . as the key path delimiter. This can be / or anything.\nvar (\n\tk      = koanf.New(\".\")\n\tparser = json.Parser()\n)\n\nfunc main() {\n\t// Load JSON config.\n\tif err := k.Load(file.Provider(\"mock/mock.json\"), parser); err != nil {\n\t\tlog.Fatalf(\"error loading config: %v\", err)\n\t}\n\n\t// Structure to unmarshal nested conf to.\n\ttype childStruct struct {\n\t\tName       string            `koanf:\"name\"`\n\t\tType       string            `koanf:\"type\"`\n\t\tEmpty      map[string]string `koanf:\"empty\"`\n\t\tGrandChild struct {\n\t\t\tIds []int `koanf:\"ids\"`\n\t\t\tOn  bool  `koanf:\"on\"`\n\t\t} `koanf:\"grandchild1\"`\n\t}\n\n\tvar out childStruct\n\n\t// Quick unmarshal.\n\tk.Unmarshal(\"parent1.child1\", \u0026out)\n\tfmt.Println(out)\n\n\t// Unmarshal with advanced config.\n\tout = childStruct{}\n\tk.UnmarshalWithConf(\"parent1.child1\", \u0026out, koanf.UnmarshalConf{Tag: \"koanf\"})\n\tfmt.Println(out)\n\n\t// Marshal the instance back to JSON.\n\t// The parser instance can be anything, eg: json.Parser(), yaml.Parser() etc.\n\tb, _ := k.Marshal(parser)\n\tfmt.Println(string(b))\n}\n```\n\n### Unmarshalling with flat paths\n\nSometimes it is necessary to unmarshal an assortment of keys from various nested structures into a flat target structure. This is possible with the `UnmarshalConf.FlatPaths` flag.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/knadh/koanf/v2\"\n\t\"github.com/knadh/koanf/parsers/json\"\n\t\"github.com/knadh/koanf/providers/file\"\n)\n\n// Global koanf instance. Use . as the key path delimiter. This can be / or anything.\nvar k = koanf.New(\".\")\n\nfunc main() {\n\t// Load JSON config.\n\tif err := k.Load(file.Provider(\"mock/mock.json\"), json.Parser()); err != nil {\n\t\tlog.Fatalf(\"error loading config: %v\", err)\n\t}\n\n\ttype rootFlat struct {\n\t\tType                        string            `koanf:\"type\"`\n\t\tEmpty                       map[string]string `koanf:\"empty\"`\n\t\tParent1Name                 string            `koanf:\"parent1.name\"`\n\t\tParent1ID                   int               `koanf:\"parent1.id\"`\n\t\tParent1Child1Name           string            `koanf:\"parent1.child1.name\"`\n\t\tParent1Child1Type           string            `koanf:\"parent1.child1.type\"`\n\t\tParent1Child1Empty          map[string]string `koanf:\"parent1.child1.empty\"`\n\t\tParent1Child1Grandchild1IDs []int             `koanf:\"parent1.child1.grandchild1.ids\"`\n\t\tParent1Child1Grandchild1On  bool              `koanf:\"parent1.child1.grandchild1.on\"`\n\t}\n\n\t// Unmarshal the whole root with FlatPaths: True.\n\tvar o1 rootFlat\n\tk.UnmarshalWithConf(\"\", \u0026o1, koanf.UnmarshalConf{Tag: \"koanf\", FlatPaths: true})\n\tfmt.Println(o1)\n\n\t// Unmarshal a child structure of \"parent1\".\n\ttype subFlat struct {\n\t\tName                 string            `koanf:\"name\"`\n\t\tID                   int               `koanf:\"id\"`\n\t\tChild1Name           string            `koanf:\"child1.name\"`\n\t\tChild1Type           string            `koanf:\"child1.type\"`\n\t\tChild1Empty          map[string]string `koanf:\"child1.empty\"`\n\t\tChild1Grandchild1IDs []int             `koanf:\"child1.grandchild1.ids\"`\n\t\tChild1Grandchild1On  bool              `koanf:\"child1.grandchild1.on\"`\n\t}\n\n\tvar o2 subFlat\n\tk.UnmarshalWithConf(\"parent1\", \u0026o2, koanf.UnmarshalConf{Tag: \"koanf\", FlatPaths: true})\n\tfmt.Println(o2)\n}\n```\n\n#### Reading from nested maps\n\nThe bundled `confmap` provider takes a `map[string]any` that can be loaded into a koanf instance. \n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/knadh/koanf/v2\"\n\t\"github.com/knadh/koanf/providers/confmap\"\n\t\"github.com/knadh/koanf/providers/file\"\n\t\"github.com/knadh/koanf/parsers/json\"\n\t\"github.com/knadh/koanf/parsers/yaml\"\n)\n\n// Global koanf instance. Use \".\" as the key path delimiter. This can be \"/\" or any character.\nvar k = koanf.New(\".\")\n\nfunc main() {\n\t// Load default values using the confmap provider.\n\t// We provide a flat map with the \".\" delimiter.\n\t// A nested map can be loaded by setting the delimiter to an empty string \"\".\n\tk.Load(confmap.Provider(map[string]any{\n\t\t\"parent1.name\": \"Default Name\",\n\t\t\"parent3.name\": \"New name here\",\n\t}, \".\"), nil)\n\n\t// Load JSON config on top of the default values.\n\tif err := k.Load(file.Provider(\"mock/mock.json\"), json.Parser()); err != nil {\n\t\tlog.Fatalf(\"error loading config: %v\", err)\n\t}\n\n\t// Load YAML config and merge into the previously loaded config (because we can).\n\tk.Load(file.Provider(\"mock/mock.yml\"), yaml.Parser())\n\n\tfmt.Println(\"parent's name is = \", k.String(\"parent1.name\"))\n\tfmt.Println(\"parent's ID is = \", k.Int(\"parent1.id\"))\n}\n```\n\n#### Reading from struct \n\nThe bundled `structs` provider can be used to read data from a struct to load into a koanf instance.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/knadh/koanf/v2\"\n\t\"github.com/knadh/koanf/providers/structs\"\n)\n\n// Global koanf instance. Use \".\" as the key path delimiter. This can be \"/\" or any character.\nvar k = koanf.New(\".\")\n\ntype parentStruct struct {\n\tName   string      `koanf:\"name\"`\n\tID     int         `koanf:\"id\"`\n\tChild1 childStruct `koanf:\"child1\"`\n}\ntype childStruct struct {\n\tName        string            `koanf:\"name\"`\n\tType        string            `koanf:\"type\"`\n\tEmpty       map[string]string `koanf:\"empty\"`\n\tGrandchild1 grandchildStruct  `koanf:\"grandchild1\"`\n}\ntype grandchildStruct struct {\n\tIds []int `koanf:\"ids\"`\n\tOn  bool  `koanf:\"on\"`\n}\ntype sampleStruct struct {\n\tType    string            `koanf:\"type\"`\n\tEmpty   map[string]string `koanf:\"empty\"`\n\tParent1 parentStruct      `koanf:\"parent1\"`\n}\n\nfunc main() {\n\t// Load default values using the structs provider.\n\t// We provide a struct along with the struct tag `koanf` to the\n\t// provider.\n\tk.Load(structs.Provider(sampleStruct{\n\t\tType:  \"json\",\n\t\tEmpty: make(map[string]string),\n\t\tParent1: parentStruct{\n\t\t\tName: \"parent1\",\n\t\t\tID:   1234,\n\t\t\tChild1: childStruct{\n\t\t\t\tName:  \"child1\",\n\t\t\t\tType:  \"json\",\n\t\t\t\tEmpty: make(map[string]string),\n\t\t\t\tGrandchild1: grandchildStruct{\n\t\t\t\t\tIds: []int{1, 2, 3},\n\t\t\t\t\tOn:  true,\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t}, \"koanf\"), nil)\n\n\tfmt.Printf(\"name is = `%s`\\n\", k.String(\"parent1.child1.name\"))\n}\n```\n### Merge behavior\n#### Default behavior\nThe default behavior when you create Koanf this way is: `koanf.New(delim)` that the latest loaded configuration will\nmerge with the previous one.\n\nFor example:\n`first.yml`\n```yaml\nkey: [1,2,3]\n```\n`second.yml`\n```yaml\nkey: 'string'\n```\nWhen `second.yml` is loaded it will override the type of the `first.yml`.\n\nIf this behavior is not desired, you can merge 'strictly'. In the same scenario, `Load` will return an error.\n\n```go\npackage main\n\nimport (\n\t\"errors\"\n\t\"log\"\n\n\t\"github.com/knadh/koanf/v2\"\n\t\"github.com/knadh/koanf/maps\"\n\t\"github.com/knadh/koanf/parsers/json\"\n\t\"github.com/knadh/koanf/parsers/yaml\"\n\t\"github.com/knadh/koanf/providers/file\"\n)\n\nvar conf = koanf.Conf{\n\tDelim:       \".\",\n\tStrictMerge: true,\n}\nvar k = koanf.NewWithConf(conf)\n\nfunc main() {\n\tyamlPath := \"mock/mock.yml\"\n\tif err := k.Load(file.Provider(yamlPath), yaml.Parser()); err != nil {\n\t\tlog.Fatalf(\"error loading config: %v\", err)\n\t}\n\n\tjsonPath := \"mock/mock.json\"\n\tif err := k.Load(file.Provider(jsonPath), json.Parser()); err != nil {\n\t\tlog.Fatalf(\"error loading config: %v\", err)\n\t}\n}\n```\n**Note:** When merging different extensions, each parser can treat his types differently,\n meaning even though you the load same types there is a probability that it will fail with `StrictMerge: true`.\n\nFor example: merging JSON and YAML will most likely fail because JSON treats integers as float64 and YAML treats them as integers.\n\n### Order of merge and key case sensitivity\n\n- Config keys are case-sensitive in koanf. For example, `app.server.port` and `APP.SERVER.port` are not the same.\n- koanf does not impose any ordering on loading config from various providers. Every successive `Load()` or `Merge()` merges new config into the existing config. That is, it is possible to load environment variables first, then files on top of it, and then command line variables on top of it, or any such order.\n\n### Custom Providers and Parsers\n\nA Provider returns a nested `map[string]any` config that can be loaded directly into koanf with `koanf.Load()` or it can return raw bytes that can be parsed with a Parser (again, loaded using `koanf.Load()`. Writing Providers and Parsers are easy. See the bundled implementations in the [providers](https://github.com/knadh/koanf/tree/master/providers) and [parsers](https://github.com/knadh/koanf/tree/master/parsers) directories.\n\n### Custom merge strategies\n\nBy default, when merging two config sources using `Load()`, koanf recursively merges keys of nested maps (`map[string]any`),\nwhile static values are overwritten (slices, strings, etc). This behaviour can be changed by providing a custom merge function with the `WithMergeFunc` option.\n\n```go\npackage main\n\nimport (\n\t\"errors\"\n\t\"log\"\n\n\t\"github.com/knadh/koanf/v2\"\n\t\"github.com/knadh/koanf/maps\"\n\t\"github.com/knadh/koanf/parsers/json\"\n\t\"github.com/knadh/koanf/parsers/yaml\"\n\t\"github.com/knadh/koanf/providers/file\"\n)\n\nvar conf = koanf.Conf{\n\tDelim:       \".\",\n\tStrictMerge: true,\n}\nvar k = koanf.NewWithConf(conf)\n\nfunc main() {\n\tyamlPath := \"mock/mock.yml\"\n\tif err := k.Load(file.Provider(yamlPath), yaml.Parser()); err != nil {\n\t\tlog.Fatalf(\"error loading config: %v\", err)\n\t}\n\n\tjsonPath := \"mock/mock.json\"\n\tif err := k.Load(file.Provider(jsonPath), json.Parser(), koanf.WithMergeFunc(func(src, dest map[string]any) error {\n     // Your custom logic, copying values from src into dst\n     return nil\n    })); err != nil {\n\t\tlog.Fatalf(\"error loading config: %v\", err)\n\t}\n}\n```\n\n## API\n\nSee the full API documentation of all available methods at https://pkg.go.dev/github.com/knadh/koanf/v2#section-documentation\n\n### Bundled Providers\n\nInstall with `go get -u github.com/knadh/koanf/providers/$provider`\n\n| Package             | Provider                                                      | Description                                                                                                                                                                           |\n| ------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| file      | `file.Provider(filepath string)`                              | Reads a file and returns the raw bytes to be parsed.                                                                                                                                  |\n| fs      | `fs.Provider(f fs.FS, filepath string)`                              | (**Experimental**) Reads a file from fs.FS and returns the raw bytes to be parsed. The provider requires `go v1.16` or higher.                                            |\n| basicflag | `basicflag.Provider(f *flag.FlagSet, delim string)`           | Takes a stdlib `flag.FlagSet`                                                                                                                                                        |\n| posflag   | `posflag.Provider(f *pflag.FlagSet, delim string)`            | Takes an `spf13/pflag.FlagSet` (advanced POSIX compatible flags with multiple types) and provides a nested config map based on delim.                                                 |\n| env/v2       | `env.Provider(prefix, delim string, f func(s string) string)` | Takes an optional prefix to filter env variables by, an optional function that takes and returns a string to transform env variables, and returns a nested config map based on delim. |\n| confmap   | `confmap.Provider(mp map[string]any, delim string)`   | Takes a premade `map[string]any` conf map. If delim is provided, the keys are assumed to be flattened, thus unflattened using delim.                                          |\n| structs   | `structs.Provider(s any, tag string)`                 | Takes a struct and struct tag.                                                                                                                                                        |\n| s3        | `s3.Provider(s3.S3Config{})`                                  | Takes a s3 config struct.                                                                                                                                                             |\n| rawbytes  | `rawbytes.Provider(b []byte)`                                 | Takes a raw `[]byte` slice to be parsed with a koanf.Parser                                                                                                                           |\n| vault/v2     | `vault.Provider(vault.Config{})`                              | Hashicorp Vault provider                                                                                                                           |\n| appconfig/v2     | `vault.AppConfig(appconfig.Config{})`                              | AWS AppConfig provider                                                                                                                           |\n| etcd/v2     | `etcd.Provider(etcd.Config{})`                              | CNCF etcd provider                                                                                                                           |\n| consul/v2     | `consul.Provider(consul.Config{})`                              | Hashicorp Consul provider                                                                                                                           |\n| parameterstore/v2 | `parameterstore.Provider(parameterstore.Config{})` | AWS Systems Manager Parameter Store provider |\n| cliflagv2  |  `cliflagv2.Provider(ctx *cli.Context, delimiter string)` |  Reads commands and flags from urfave/cli/v2 context including global flags and nested command flags and provides a nested config map based on delim. |\n| cliflagv3  |  `cliflagv3.Provider(ctx *cli.Context, delimiter string)` |  Reads commands and flags from urfave/cli/v3 and provides a nested config map based on delim. |\n| kiln   |  `kiln.Provider(configPath, keyPath, file string)` | Takes an optional prefix to filter environment variables keys by, an optional function that takes and returns a string to transform environment variables, and returns a nested config map. |\n\n\n### Bundled Parsers\n\nInstall with `go get -u github.com/knadh/koanf/parsers/$parser`\n\n| Package      | Parser                           | Description                                                                                                                                               |\n| ------------ | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| json       | `json.Parser()`                  | Parses JSON bytes into a nested map                                                                                                                       |\n| yaml       | `yaml.Parser()`                  | Parses YAML bytes into a nested map                                                                                                                       |\n| toml       | `toml.Parser()`                  | Parses TOML bytes into a nested map                                                                                                                       |\n| toml/v2    | `toml.Parser()`                  | Parses TOML bytes into a nested map (using go-toml v2)                                                                                                    |\n| dotenv     | `dotenv.Parser()`              | Parses DotEnv bytes into a flat map                                                                                                                       |\n| hcl        | `hcl.Parser(flattenSlices bool)` | Parses Hashicorp HCL bytes into a nested map. `flattenSlices` is recommended to be set to true. [Read more](https://github.com/hashicorp/hcl/issues/162). |\n| hjson\t\t | `hjson.Parser()`\t\t\t\t\t| Parses HJSON bytes into a nested map                                                                                                                     |\n| huml       | `huml.Parser()`                   | Parses HUML (Human-Oriented Markup Language) bytes into a nested map                                                                                     |\n| nestedtext | `nestedtext.Parser()`              | Parses NestedText bytes into a flat map                                                                                                                 |\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t|\n\n\n### Third-party Providers\n| Package             | Provider                                                      | Description                                                                                                                                                                           |\n| ------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| github.com/defensestation/koanf/providers/secretsmanager     | `vault.SecretsManager(secretsmanager.Config{}, f func(s string) string)`                              | AWS Secrets Manager provider, takes map or string as a value from store                                                \t\t\t\t\t\t  |\n| github.com/defensestation/koanf/providers/parameterstore     | `vault.ParameterStore(parameterstore.Config{}, f func(s string) string)`                              | AWS ParameterStore provider, an optional function that takes and returns a string to transform env variables                                                 \t\t\t\t\t\t  |\n\n\n### Alternative to viper\n\nkoanf is a [lightweight](https://github.com/knadh/koanf/blob/master/go.mod) alternative to the popular [spf13/viper](https://github.com/spf13/viper). It was written as a result of multiple stumbling blocks encountered with some of viper's fundamental flaws.\n\n- viper breaks JSON, YAML, TOML, HCL language specs by [forcibly lowercasing keys](https://github.com/spf13/viper/pull/635).\n- Significantly bloats [build sizes](https://github.com/knadh/koanf/wiki/Comparison-with-spf13-viper).\n- Tightly couples config parsing with file extensions.\n- Has poor semantics and abstractions. Commandline, env, file etc. and various parses are hardcoded in the core. There are no primitives that can be extended.\n- Pulls a large number of [third party dependencies](https://github.com/spf13/viper/issues/707) into the core package. For instance, even if you do not use YAML or flags, the dependencies are still pulled as a result of the coupling.\n- Imposes arbitrary ordering conventions (eg: flag -\u003e env -\u003e config etc.)\n- `Get()` returns references to slices and maps. Mutations made outside change the underlying values inside the conf map.\n- Does non-idiomatic things such as [throwing away O(1) on flat maps](https://github.com/spf13/viper/blob/3b4aca75714a37276c4b1883630bd98c02498b73/viper.go#L1524).\n- Viper treats keys that contain an empty map (eg: `my_key: {}`) as if they were not set (ie: `IsSet(\"my_key\") == false`).\n- There are a large number of [open issues](https://github.com/spf13/viper/issues).\n","funding_links":[],"categories":["配置","开源类库","Configuration","Go","Programming","Open source library","yaml","Repositories","Uncategorized","配置管理 `配置解析库`","配置管理"],"sub_categories":["标准CLI","配置","Standard CLI","Go","Construction","Advanced Console UIs","标准 CLI"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknadh%2Fkoanf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknadh%2Fkoanf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknadh%2Fkoanf/lists"}