{"id":13395078,"url":"https://github.com/bkeepers/dotenv","last_synced_at":"2025-05-12T16:24:43.563Z","repository":{"id":4057484,"uuid":"5160706","full_name":"bkeepers/dotenv","owner":"bkeepers","description":"A Ruby gem to load environment variables from `.env`. ","archived":false,"fork":false,"pushed_at":"2025-04-10T15:19:25.000Z","size":713,"stargazers_count":6659,"open_issues_count":11,"forks_count":513,"subscribers_count":69,"default_branch":"main","last_synced_at":"2025-05-05T08:52:16.617Z","etag":null,"topics":["dotenv","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/bkeepers.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":".github/funding.yml","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},"funding":{"github":["bkeepers"]}},"created_at":"2012-07-24T03:38:51.000Z","updated_at":"2025-05-04T15:31:50.000Z","dependencies_parsed_at":"2024-02-01T19:35:47.370Z","dependency_job_id":"ec4f47ab-6715-4d2f-8362-8cdd838ee18f","html_url":"https://github.com/bkeepers/dotenv","commit_stats":{"total_commits":523,"total_committers":125,"mean_commits":4.184,"dds":0.5449330783938815,"last_synced_commit":"ee3975c208b2f490835cf49a9cebf61d529c0415"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkeepers%2Fdotenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkeepers%2Fdotenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkeepers%2Fdotenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkeepers%2Fdotenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bkeepers","download_url":"https://codeload.github.com/bkeepers/dotenv/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252474237,"owners_count":21753630,"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":["dotenv","ruby"],"created_at":"2024-07-30T17:01:41.263Z","updated_at":"2025-05-05T12:54:48.944Z","avatar_url":"https://github.com/bkeepers.png","language":"Ruby","funding_links":["https://github.com/sponsors/bkeepers"],"categories":["Environment Variables","Container registries","Ruby","Usage","Tools","tools","Configuration","Developer Tools","Python Frameworks and Tools","环境变量","Uncategorized","Gems","Ruby Tools","Ruby Tools and Frameworks","Tools and Utilities","Development","Environment Management","其他"],"sub_categories":["Omniauth","Security","Authentication","Interfaces","Configuration Management","Uncategorized","Configuration and environment variables","E-Books","Mesh networks","JavaScript Libraries for Machine Learning"],"readme":"# dotenv [![Gem Version](https://badge.fury.io/rb/dotenv.svg)](https://badge.fury.io/rb/dotenv)\n\nShim to load environment variables from `.env` into `ENV` in *development*.\n\n\u003cimg align=\"left\" src=\"https://github.com/user-attachments/assets/0052ed0b-00d2-416a-bdaa-0466c0226933\" width=\"80\" /\u003e\n\u003cdiv\u003e\u003csup\u003eDotenv is proud to be \u003ca href=\"https://github.com/sponsors/bkeepers\"\u003esponsored by\u003c/a\u003e:\u003c/sup\u003e\u003c/div\u003e\n\u003cstrong\u003e\u003ca href=\"https://bit.ly/dotenv-stoked-seagull\"\u003eStoked Seagull Software\u003c/a\u003e\u003c/strong\u003e\n\u003cdiv\u003eNeed help with a software project but don't know where to begin? \u003ca href=\"https://bit.ly/dotenv-stoked-seagull\"\u003eStoked Seagull can help.\u003c/a\u003e\u003c/div\u003e\u003cbr\u003e\u003cbr\u003e\n\nStoring [configuration in the environment](http://12factor.net/config) is one of the tenets of a [twelve-factor app](http://12factor.net). 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\nBut it is not always practical to set environment variables on development machines or continuous integration servers where multiple projects are run. dotenv loads variables from a `.env` file into `ENV` when the environment is bootstrapped.\n\n## Installation\n\nAdd this line to the top of your application's Gemfile and run `bundle install`:\n\n```ruby\ngem 'dotenv', groups: [:development, :test]\n```\n\n## Usage\n\nAdd your application configuration to your `.env` file in the root of your project:\n\n```shell\nS3_BUCKET=YOURS3BUCKET\nSECRET_KEY=YOURSECRETKEYGOESHERE\n```\n\nWhenever your application loads, these variables will be available in `ENV`:\n\n```ruby\nconfig.fog_directory = ENV['S3_BUCKET']\n```\n\nSee the [API Docs](https://rubydoc.info/github/bkeepers/dotenv/main) for more.\n\n### Rails\n\nDotenv will automatically load when your Rails app boots. See [Customizing Rails](#customizing-rails) to change which files are loaded and when.\n\n### Sinatra / Ruby\n\nLoad Dotenv as early as possible in your application bootstrap process:\n\n```ruby\nrequire 'dotenv/load'\n\n# or\nrequire 'dotenv'\nDotenv.load\n```\n\nBy default, `load` will look for a file called `.env` in the current working directory. Pass in multiple files and they will be loaded in order. The first value set for a variable will win.\n\n```ruby\nrequire 'dotenv'\nDotenv.load('file1.env', 'file2.env')\n```\n\n### Autorestore in tests\n\nSince 3.0, dotenv in a Rails app will automatically restore `ENV` after each test. This means you can modify `ENV` in your tests without fear of leaking state to other tests. It works with both `ActiveSupport::TestCase` and `Rspec`.\n\nTo disable this behavior, set `config.dotenv.autorestore = false` in `config/application.rb` or `config/environments/test.rb`. It is disabled by default if your app uses [climate_control](https://github.com/thoughtbot/climate_control) or [ice_age](https://github.com/dpep/ice_age_rb).\n\nTo use this behavior outside of a Rails app, just `require \"dotenv/autorestore\"` in your test suite.\n\nSee [`Dotenv.save`](https://rubydoc.info/github/bkeepers/dotenv/main/Dotenv:save), [Dotenv.restore](https://rubydoc.info/github/bkeepers/dotenv/main/Dotenv:restore), and [`Dotenv.modify(hash) { ... }`](https://rubydoc.info/github/bkeepers/dotenv/main/Dotenv:modify) for manual usage.\n\n### Rake\n\nTo ensure `.env` is loaded in rake, load the tasks:\n\n```ruby\nrequire 'dotenv/tasks'\n\ntask mytask: :dotenv do\n  # things that require .env\nend\n```\n\n### CLI\n\nYou can use the `dotenv` executable load `.env` before launching your application:\n\n```console\n$ dotenv ./script.rb\n```\n\nThe `dotenv` executable also accepts the flag `-f`. Its value should be a comma-separated list of configuration files, in the order of the most important to the least important. All of the files must exist. There _must_ be a space between the flag and its value.\n\n```console\n$ dotenv -f \".env.local,.env\" ./script.rb\n```\n\nThe `dotenv` executable can optionally ignore missing files with the `-i` or `--ignore` flag. For example, if the `.env.local` file does not exist, the following will ignore the missing file and only load the `.env` file.\n\n```console\n$ dotenv -i -f \".env.local,.env\" ./script.rb\n```\n\n### Load Order\n\nIf you use gems that require environment variables to be set before they are loaded, then list `dotenv` in the `Gemfile` before those other gems and require `dotenv/load`.\n\n```ruby\ngem 'dotenv', require: 'dotenv/load'\ngem 'gem-that-requires-env-variables'\n```\n\n### Customizing Rails\n\nDotenv will load the following files depending on `RAILS_ENV`, with the first file having the highest precedence, and `.env` having the lowest precedence:\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth\u003ePriority\u003c/th\u003e\n      \u003cth colspan=\"3\"\u003eEnvironment\u003c/th\u003e\n      \u003cth\u003e\u003ccode\u003e.gitignore\u003c/code\u003eit?\u003c/th\u003e\n      \u003cth\u003eNotes\u003c/th\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e\u003c/th\u003e\n      \u003cth\u003edevelopment\u003c/th\u003e\n      \u003cth\u003etest\u003c/th\u003e\n      \u003cth\u003eproduction\u003c/th\u003e\n      \u003cth\u003e\u003c/th\u003e\n      \u003cth\u003e\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctr\u003e\n    \u003ctd\u003ehighest\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003e.env.development.local\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003e.env.test.local\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003e.env.production.local\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eYes\u003c/td\u003e\n    \u003ctd\u003eEnvironment-specific local overrides\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e2nd\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003e.env.local\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cstrong\u003eN/A\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003e.env.local\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eYes\u003c/td\u003e\n    \u003ctd\u003eLocal overrides\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e3rd\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003e.env.development\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003e.env.test\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003e.env.production\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eNo\u003c/td\u003e\n    \u003ctd\u003eShared environment-specific variables\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003elast\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003e.env\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003e.env\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003e.env\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"#should-i-commit-my-env-file\"\u003eMaybe\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eShared for all environments\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\nThese files are loaded during the `before_configuration` callback, which is fired when the `Application` constant is defined in `config/application.rb` with `class Application \u003c Rails::Application`. If you need it to be initialized sooner, or need to customize the loading process, you can do so at the top of `application.rb`\n\n```ruby\n# config/application.rb\nBundler.require(*Rails.groups)\n\n# Load .env.local in test\nDotenv::Rails.files.unshift(\".env.local\") if ENV[\"RAILS_ENV\"] == \"test\"\n\nmodule YourApp\n  class Application \u003c Rails::Application\n    # ...\n  end\nend\n```\n\nAvailable options:\n\n* `Dotenv::Rails.files` - list of files to be loaded, in order of precedence.\n* `Dotenv::Rails.overwrite` - Overwrite existing `ENV` variables with contents of `.env*` files\n* `Dotenv::Rails.logger` - The logger to use for dotenv's logging. Defaults to `Rails.logger`\n* `Dotenv::Rails.autorestore` - Enable or disable [autorestore](#autorestore-in-tests)\n\n### Multi-line values\n\nMulti-line values with line breaks must be surrounded with double quotes.\n\n```shell\nPRIVATE_KEY=\"-----BEGIN RSA PRIVATE KEY-----\n...\nHkVN9...\n...\n-----END DSA PRIVATE KEY-----\"\n```\n\nPrior to 3.0, dotenv would replace `\\n` in quoted strings with a newline, but that behavior is deprecated. To use the old behavior, set `DOTENV_LINEBREAK_MODE=legacy` before any variables that include `\\n`:\n\n```shell\nDOTENV_LINEBREAK_MODE=legacy\nPRIVATE_KEY=\"-----BEGIN RSA PRIVATE KEY-----\\nHkVN9...\\n-----END DSA PRIVATE KEY-----\\n\"\n```\n\n### Command Substitution\n\nYou need to add the output of a command in one of your variables? Simply add it with `$(your_command)`:\n\n```shell\nDATABASE_URL=\"postgres://$(whoami)@localhost/my_database\"\n```\n\n### Variable Substitution\n\nYou need to add the value of another variable in one of your variables? You can reference the variable with `${VAR}` or often just `$VAR` in unquoted or double-quoted values.\n\n```shell\nDATABASE_URL=\"postgres://${USER}@localhost/my_database\"\n```\n\nIf a value contains a `$` and it is not intended to be a variable, wrap it in single quotes.\n\n```shell\nPASSWORD='pas$word'\n```\n\n### Comments\n\nComments may be added to your file as such:\n\n```shell\n# This is a comment\nSECRET_KEY=YOURSECRETKEYGOESHERE # comment\nSECRET_HASH=\"something-with-a-#-hash\"\n```\n\n### Exports\n\nFor compatability, you may also add `export` in front of each line so you can `source` the file in bash:\n\n```shell\nexport S3_BUCKET=YOURS3BUCKET\nexport SECRET_KEY=YOURSECRETKEYGOESHERE\n```\n\n### Required Keys\n\nIf a particular configuration value is required but not set, it's appropriate to raise an error.\n\nTo require configuration keys:\n\n```ruby\n# config/initializers/dotenv.rb\n\nDotenv.require_keys(\"SERVICE_APP_ID\", \"SERVICE_KEY\", \"SERVICE_SECRET\")\n```\n\nIf any of the configuration keys above are not set, your application will raise an error during initialization. This method is preferred because it prevents runtime errors in a production application due to improper configuration.\n\n### Parsing\n\nTo parse a list of env files for programmatic inspection without modifying the ENV:\n\n```ruby\nDotenv.parse(\".env.local\", \".env\")\n# =\u003e {'S3_BUCKET' =\u003e 'YOURS3BUCKET', 'SECRET_KEY' =\u003e 'YOURSECRETKEYGOESHERE', ...}\n```\n\nThis method returns a hash of the ENV var name/value pairs.\n\n### Templates\n\nYou can use the `-t` or `--template` flag on the dotenv cli to create a template of your `.env` file.\n\n```console\n$ dotenv -t .env\n```\nA template will be created in your working directory named `{FILENAME}.template`. So in the above example, it would create a `.env.template` file.\n\nThe template will contain all the environment variables in your `.env` file but with their values set to the variable names.\n\n```shell\n# .env\nS3_BUCKET=YOURS3BUCKET\nSECRET_KEY=YOURSECRETKEYGOESHERE\n```\n\nWould become\n\n```shell\n# .env.template\nS3_BUCKET=S3_BUCKET\nSECRET_KEY=SECRET_KEY\n```\n\n## Frequently Answered Questions\n\n### Can I use dotenv in production?\n\ndotenv was originally created to load configuration variables into `ENV` in *development*. There are typically better ways to manage configuration in production environments - such as `/etc/environment` managed by [Puppet](https://github.com/puppetlabs/puppet) or [Chef](https://github.com/chef/chef), `heroku config`, etc.\n\nHowever, some find dotenv to be a convenient way to configure Rails applications in staging and production environments, and you can do that by defining environment-specific files like `.env.production` or `.env.test`.\n\nIf you use this gem to handle env vars for multiple Rails environments (development, test, production, etc.), please note that env vars that are general to all environments should be stored in `.env`. Then, environment specific env vars should be stored in `.env.\u003cthat environment's name\u003e`.\n\n### Should I commit my .env file?\n\nCredentials should only be accessible on the machines that need access to them. Never commit sensitive information to a repository that is not needed by every development machine and server.\n\nPersonally, I prefer to commit the `.env` file with development-only settings. This makes it easy for other developers to get started on the project without compromising credentials for other environments. If you follow this advice, make sure that all the credentials for your development environment are different from your other deployments and that the development credentials do not have access to any confidential data.\n\n### Why is it not overwriting existing `ENV` variables?\n\nBy default, it **won't** overwrite existing environment variables as dotenv assumes the deployment environment has more knowledge about configuration than the application does. To overwrite existing environment variables you can use `Dotenv.load files, overwrite: true`.\n\nYou can also use the `-o` or `--overwrite` flag on the dotenv cli to overwrite existing `ENV` variables.\n\n```console\n$ dotenv -o -f \".env.local,.env\"\n```\n\n## Contributing\n\nIf you want a better idea of how dotenv works, check out the [Ruby Rogues Code Reading of dotenv](https://www.youtube.com/watch?v=lKmY_0uY86s).\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Added some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkeepers%2Fdotenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbkeepers%2Fdotenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkeepers%2Fdotenv/lists"}