{"id":13537851,"url":"https://github.com/cdimascio/dotenv-kotlin","last_synced_at":"2025-05-14T19:10:06.781Z","repository":{"id":38304979,"uuid":"112032910","full_name":"cdimascio/dotenv-kotlin","owner":"cdimascio","description":"🗝️ Dotenv is a module that loads environment variables from a .env file","archived":false,"fork":false,"pushed_at":"2025-02-22T16:52:42.000Z","size":560,"stargazers_count":534,"open_issues_count":4,"forks_count":27,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-13T15:08:15.335Z","etag":null,"topics":["12-factor","android","dotenv","environment-configuration","environment-variables","hacktoberfest","java","jvm","kotlin"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cdimascio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGE_HISTORY.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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},"funding":{"custom":"https://www.buymeacoffee.com/m97tA5c"}},"created_at":"2017-11-25T20:37:33.000Z","updated_at":"2025-04-04T16:10:45.000Z","dependencies_parsed_at":"2024-04-26T07:44:54.838Z","dependency_job_id":"3de02a21-60b7-4025-946c-2cbc722257c4","html_url":"https://github.com/cdimascio/dotenv-kotlin","commit_stats":{"total_commits":331,"total_committers":16,"mean_commits":20.6875,"dds":0.5709969788519638,"last_synced_commit":"e8008bd744c7ac2529eba4d5de7207fac654031c"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdimascio%2Fdotenv-kotlin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdimascio%2Fdotenv-kotlin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdimascio%2Fdotenv-kotlin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdimascio%2Fdotenv-kotlin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cdimascio","download_url":"https://codeload.github.com/cdimascio/dotenv-kotlin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254209859,"owners_count":22032897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["12-factor","android","dotenv","environment-configuration","environment-variables","hacktoberfest","java","jvm","kotlin"],"created_at":"2024-08-01T09:01:04.298Z","updated_at":"2025-05-14T19:10:04.858Z","avatar_url":"https://github.com/cdimascio.png","language":"Kotlin","funding_links":["https://www.buymeacoffee.com/m97tA5c"],"categories":["Libraries","Kotlin"],"sub_categories":[],"readme":"# 🗝️ dotenv-kotlin \n\n![](https://travis-ci.org/cdimascio/dotenv-kotlin.svg?branch=master) [![Coverage Status](https://coveralls.io/repos/github/cdimascio/dotenv-kotlin/badge.svg?branch=v6)](https://coveralls.io/github/cdimascio/dotenv-kotlin?branch=master) [![Maven Central](https://img.shields.io/maven-central/v/io.github.cdimascio/dotenv-kotlin.svg?label=Maven%20Central)](https://search.maven.org/artifact/io.github.cdimascio/dotenv-kotlin) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/66b8195f0da544f1ad9ed1352c0ea66f)](https://app.codacy.com/app/cdimascio/dotenv-kotlin?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=cdimascio/dotenv-kotlinv\u0026utm_campaign=Badge_Grade_Dashboard) [![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors) [![](https://img.shields.io/gitter/room/cdimascio-oss/community?color=%23eb205a)](https://gitter.im/cdimascio-oss/community) ![](https://img.shields.io/badge/license-Apache%202.0-orange.svg)\n\nA port of the Ruby dotenv project for Java and Kotlin. Load environment variables from a `.env` file.\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"https://raw.githubusercontent.com/cdimascio/dotenv-kotlin/master/assets/kotlin-dotenv-logo.png\" alt=\"dotenv\" /\u003e \n\u003c/p\u003e\n\nLooking for the _pure Java_ version? Get **[dotenv-java](https://github.com/cdimascio/dotenv-java)**.\n\nWhy dotenv?\n\n\u003eStoring configuration in the environment is one of the tenets of a [twelve-factor](http://12factor.net/config) app. Anything that is likely to change between deployment environments–such as resource handles for databases or credentials for external services–should be extracted from the code into environment variables.\n\n\u003eBut it is not always practical to set environment variables on development machines or continuous integration servers where multiple projects are run. Dotenv load variables from a .env file into ENV when the environment is bootstrapped.\n\n\u003e-- [Brandon Keepers](https://github.com/bkeepers/dotenv)\n\n\nEnvironment variables listed in the host environment override those in `.env`.  \n\nUse `dotenv.get(\"...\")` instead of Java's `System.getenv(...)`.  \n\n## Install\n\nLooking for the pure Java variant (no Kotlin), get [dotenv-java](https://github.com/cdimascio/dotenv-java).\n\n### Maven \n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.cdimascio\u003c/groupId\u003e\n    \u003cartifactId\u003edotenv-kotlin\u003c/artifactId\u003e\n    \u003cversion\u003e6.5.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n[Previous versions](https://github.com/cdimascio/java-dotenv#Previous-Versions-of-java-dotenv)\n\n### Gradle\n#### Gradle Groovy DSL\n```groovy\nimplementation 'io.github.cdimascio:dotenv-kotlin:6.5.1'\n```\n\n#### Gradle Kotlin DSL\n```kotlin\nimplementation(\"io.github.cdimascio:dotenv-kotlin:6.5.1\")\n```\n\n## Usage\nUse `dotenv.get(\"...\")` instead of Java's `System.getenv(...)`. Here's [why](#faq).\n\nCreate a `.env` file in the root of your project\n\n```dosini\n# formatted as key=value\nMY_ENV_VAR1=some_value\nMY_EVV_VAR2=some_value\nMY_ENV_MULTI_LINE=\"some\nmultiline\nvalue\"\n```\n\nWith **Java**\n\n```java\nimport io.github.cdimascio.dotenv.Dotenv;\n\nDotenv dotenv = Dotenv.load();\ndotenv.get(\"MY_ENV_VAR1\");\n```\n\nor with **Kotlin** \n\n```kotlin\nimport io.github.cdimascio.dotenv.dotenv\n\nval dotenv = dotenv()\ndotenv[\"MY_ENV_VAR1\"]\n```\n\n## Android Usage\n\n- Create an assets folder\n- Add `env` *(no dot)* to the assets folder.\n\n\t\u003cimg src=\"assets/android-dotenv.png\" width=\"350\"\u003e\n\n- Configure dotenv to search `/assets` for a file with name `env`\n\n\t```kotlin\n\tval dotenv = dotenv {\n\t    directory = \"/assets\"\n\t    filename = \"env\" // instead of '.env', use 'env'\n\t}\n\tdotenv[\"MY_ENV_VAR1\"]\n\t```\n\n**Note:** The above configuration is required because dot files in `/assets` do not appear to resolve on Android. *(Seeking recommendations from the Android community on how `dotenv-kotlin` configuration should work in order to provide the best experience for Android developers)*\n\nAlternatively, if you are using Provider `android.resource` you may specify\n\n```\n directory = \"android.resource://com.example.dimascio.myapp/raw\"\n```\n\n## Flutter Usage\nAdvices to use the package in the native Android layer prior to the flutter initialization.\n\n* Create an assets folder inside `/android/app/src/main/`\n* Add `env` (not dot) file to the assets folder.\n* Configure dotenv to search ./assets for a file with name `env`.\n```kotlin\n\tval dotenv = dotenv {\n\t    directory = \"./assets\"\n\t    filename = \"env\" // instead of '.env', use 'env'\n\t}\n\tdotenv[\"MY_ENV_VAR1\"] ?: \"\"\n```\n* Is a good practice to ignore the env file from the repository. For this purpose you can use the `.gitignore` inside the android folder\n\n## Advanced Usage\n\n### Configure\nConfigure `dotenv-kotlin` once in your application. \n\nWith **Java**\n\n```java\nDotenv dotenv = Dotenv.configure()\n        .directory(\"./some/path\")\n        .ignoreIfMalformed()\n        .ignoreIfMissing()\n        .load();\n```\n\n- see [configuration options](#configuration-options)\n\nor with **Kotlin**\n\n```kotlin\nval dotenv = dotenv {\n    directory = \"./some/path\"\n    ignoreIfMalformed = true\n    ignoreIfMissing = true\n}\n```\n\n- see [Kotlin DSL configuration options](#configuration-options)\n\n### Get environment variables\nNote, environment variables specified in the host environment take precedence over those in `.env`.\n\nWith **Java**\n\n```java\ndotenv.get(\"HOME\");\ndotenv.get(\"MY_ENV_VAR1\", \"default value\");\n```\n\nor with **Kotlin**\n\n```kotlin\ndotenv[\"HOME\"]\ndotenv[\"MY_ENV_VAR1\"] ?: \"default value\"\n```\n\n### Iterate over environment variables\nNote, environment variables specified in the host environment take precedence over those in `.env`.\n\nWith **Java**\n\n```java\nfor (DotenvEntry e : dotenv.entries()) {\n    System.out.println(e.getKey());\n    System.out.println(e.getValue());\n}\n```\n\nor with **Kotlin**\n\n```kotlin\nfor (e in dotenv.entries()) {\n    println(e.key)\n    println(e.value)\n}\n```\n\n## Configuration options\n\n### *optional* `directory` \n* `path` specifies the directory containing `.env`. Dotenv first searches for `.env` using the given path on the filesystem. If not found, it searches the given path on the classpath. If `directory` is not specified it defaults to searching the current working directory on the filesystem. If not found, it searches the current directory on the classpath.\n\n\t**Java example**\n\t\n\t```java\n\tDotenv\n\t  .configure()\n\t  .directory(\"/some/path\")\n\t  .load()\n\t```\n\n\t**Kotlin Dsl example**\n\t\n\t```kotlin\n\tdotenv {\n\t  directory = \"/some/path\"\n\t}\n    ```\n\n### *optional* `filename`\n\n* Use a filename other than `.env`. Recommended for use with Android (see [details](#android-usage)) \n\n\t**Java example**\n\t\n\t```java\n\tDotenv\n\t  .configure()\n\t  .filename(\"myenv\")\n\t  .load();\n\t```\n\t**Kotlin Dsl example**\n\t\n\t```kotlin\n\tdotenv {\n\t    filename = \"myenv\"\n\t}\n\t```\n\n### *optional* `ignoreIfMalformed`\n\n* Do not throw when `.env` entries are malformed. Malformed entries are skipped.\n\n\t**Java example**\n\t\n\t```java\n\tDotenv\n\t  .configure()\n\t  .ignoreIfMalformed()\n\t  .load();\n\t```\n\t**Kotlin Dsl example**\n\t\n\t```kotlin\n\tdotenv {\n\t  ignoreIfMalformed = true\n\t}\n\t```\n\n### *optional* `ignoreIfMissing` \n\n* Do not throw when `.env` does not exist. Dotenv will continue to retrieve environment variables that are set in the environment e.g. `dotenv[\"HOME\"]`\n\n\t**Java example**\n\t\n\t```java\n\tDotenv\n\t  .configure()\n\t  .ignoreIfMissing()\n\t  .load();\n\t```\n\t**Kotlin Dsl example**\n\t\n\t```kotlin\n\tdotenv {\n\t  ignoreIfMissing = true\n\t}\n\t```\n\n### *optional* `systemProperties` \n\n* Load environment variables into System properties, thus making all environment variables accessible via `System.getProperty(...)`\n\n\t**Java example**\n\t\n\t```java\n\tDotenv\n\t  .configure()\n\t  .systemProperties()\n\t  .load();\n\t```\n\t**Kotlin Dsl example**\n\t\n\t```kotlin\n\tdotenv {\n\t  systemProperties = true\n\t}\n\t```\n\n## Examples\n- with [Maven (simple)](https://github.com/cdimascio/dotenv-kotlin-example)\n- with [Spring MVC](https://github.com/cdimascio/kotlin-spring-mvc-template)\n- with [Spring Webflux](https://github.com/cdimascio/kotlin-swagger-spring-functional-template)\n- with [Android](https://github.com/cdimascio/android-example/blob/master/app/src/main/java/com/example/dimascio/myapp/MainActivity.kt) \n- see [Kotlin DSL tests](./src/test/kotlin/tests/DslTests.kt)\n- see [Java tests](./src/test/java/tests/JavaTests.java)\n\n## FAQ\n\n**Q:** Should I deploy a `.env` to e.g. production?\n\n**A**: Tenant III of the [12 factor app methodology](https://12factor.net/config) states \"The twelve-factor app stores config in environment variables\". Thus, it is not recommended to provide the .env file to such environments. dotenv, however, is super useful in e.g a local development environment as it enables a developer to manage the environment via a file which is more convenient.\n\nUsing dotenv in production would be cheating. This type of usage, however is an anti-pattern.\n\n**Q:** Why should I use `dotenv.get(\"MY_ENV_VAR\")` instead of `System.getenv(\"MY_ENV_VAR\")`\n\n**A**: Since Java does not provide a way to set environment variables on a currently running process, vars listed in `.env` cannot be set and thus cannot be retrieved using `System.getenv(...)`.\n\n**Q**: Can I use `System.getProperty(...)` to retrieve environment variables?\n\n**A**: Sure. Use the `systemProperties` option. Or after initializing dotenv set each env var into system properties manually. For example:\n\nJava\n```java\nDotenv dotenv = Dotenv.configure().load();\ndotenv.entries().forEach(e -\u003e System.setProperty(e.getKey(), e.getValue()));\nSystem.getProperty(\"MY_VAR\");\n```\n\nKotlin\n```kotlin\nval dotenv = dotenv()\ndotenv.entries().forEach { (key, value) -\u003e System.setProperty(key, value) }\n```\n\n**Q:** Should I have multiple .env files?\n\n**A**: No. We strongly recommend against having a \"main\" .env file and an \"environment\" .env file like .env.test. Your config should vary between deploys, and you should not be sharing values between environments.\n\n\u003e In a twelve-factor app, env vars are granular controls, each fully orthogonal to other env vars. They are never grouped together as “environments”, but instead are independently managed for each deploy. This is a model that scales up smoothly as the app naturally expands into more deploys over its lifetime.\n\n\u003e– The Twelve-Factor App\n\n**Q**: Should I commit my `.env` file?\n\n**A**: No. We strongly recommend against committing your `.env` file to version control. It should only include environment-specific values such as database passwords or API keys. Your production database should have a different password than your development database.\n\n**Q**: What happens to environment variables that were already set?\n\n**A**: dotenv-kotlin will never modify any environment variables that have already been set. In particular, if there is a variable in your `.env` file which collides with one that already exists in your environment, then that variable will be skipped. This behavior allows you to override all `.env` configurations with a machine-specific environment, although it is not recommended.\n\n**Q**: What about variable expansion in `.env`? \n\n**A**: We haven't been presented with a compelling use case for expanding variables and believe it leads to env vars that are not \"fully orthogonal\" as [The Twelve-Factor App outlines](https://12factor.net/config). Please open an issue if you have a compelling use case.\n\n**Q**: Can I supply a multi-line value?\n\n**A**: dotenv-kotlin exhibits the same behavior as Java's `System.getenv(...)`, thus if a multi-line value is needed you might consider encoding it via e.g. Base64. see this [comment](https://github.com/cdimascio/dotenv-kotlin/issues/28#issuecomment-489443975) for details.\n\n\n**Note and reference**: The FAQs present on [motdotla's dotenv](https://github.com/motdotla/dotenv#faq) node project page are so well done that I've included those that are relevant in the FAQs above.\n\n## Contributors\nContributions are welcome!\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://www.twitter.com/carminedimascio\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/4706618?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eCarmine DiMascio\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/cdimascio/dotenv-kotlin/commits?author=cdimascio\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/cdimascio/dotenv-kotlin/commits?author=cdimascio\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#infra-cdimascio\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e🚇\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/arniu\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/1286674?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eArniu Tseng\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/cdimascio/dotenv-kotlin/commits?author=arniu\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/cdimascio/dotenv-kotlin/commits?author=arniu\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#infra-arniu\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e🚇\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://pwoolcoc.gitlab.io\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/620392?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003ePaul Woolcock\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#ideas-pwoolcoc\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/Playacem\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/3692093?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003ePlayacem\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/cdimascio/dotenv-kotlin/commits?author=Playacem\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://cleymax.fr/\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/24879740?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eClément P.\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/cdimascio/dotenv-kotlin/commits?author=Cleymax\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/HarryHenryGebel\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/1482486?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eHarry Henry Gebel\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/cdimascio/dotenv-kotlin/commits?author=HarryHenryGebel\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://twitch.tv/NyCodeGHG\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/37078297?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eNyCode\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/cdimascio/dotenv-kotlin/commits?author=NyCodeGHG\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nsee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## License\n\nsee [LICENSE](LICENSE) ([Apache 2.0](LICENSE))\n\n\u003ca href=\"https://www.buymeacoffee.com/m97tA5c\" target=\"_blank\"\u003e\u003cimg src=\"https://bmc-cdn.nyc3.digitaloceanspaces.com/BMC-button-images/custom_images/orange_img.png\" alt=\"Buy Me A Coffee\" style=\"height: auto !important;width: auto !important;\" \u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdimascio%2Fdotenv-kotlin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcdimascio%2Fdotenv-kotlin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdimascio%2Fdotenv-kotlin/lists"}