Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Easiest way to add multi-environment yaml settings to Rails, Sinatra, Pandrino and other ruby projects.
Ruby HTML CSS JavaScript

Build Status Gem Version Dependency Status Code Climate Test Coverage



Config helps you easily manage environment specific settings in an easy and usable manner.


  • simple YAML config files
  • config files support ERB
  • config files support inheritance
  • access config information via convenient object member notation


  • Ruby 2.x
  • Rails >= 3.1 and 4
  • Padrino
  • Sinatra

For older versions of Rails and other Ruby apps, use AppConfig.

Installing on Rails 3 or 4

Add this to your Gemfile:

gem "config"

If you want to use Settings before rails application initialization process you can load Config railtie manually:

module Appname
  class Application < Rails::Application


    # ...

    config.time_zone = Settings.time_zone

    # ...


Installing on Padrino

Add this to your Gemfile:

gem "config"

in your app.rb, you'll also need to register Config

register Config

Installing on Sinatra

Add this to your Gemfile:

gem "config"

in your app, you'll need to register Config. You'll also need to give it a root so it can find the config files.

set :root, File.dirname(__FILE__)
register Config

It's also possible to initialize it manually within your configure block if you want to just give it some yml paths to load from.

Config.load_and_set_settings("/path/to/yaml1", "/path/to/yaml2", ...)

Customizing Config

You may customize the behavior of Config by generating an initializer file:

rails g config:install

This will generate config/initializers/config.rb with a set of default settings as well as to generate a set of default settings files:


Accessing the Settings object

After installing this plugin, the Settings object will be available globally. Entries are accessed via object member notation:


Nested entries are supported:


Alternatively, you can also use the [] operator if you don't know which exact setting you need to access ahead of time.

# All the following are equivalent to Settings.my_section.some_entry

If you have set a different constant name for the object in the initializer file, use that instead.

Common config file

Config entries are compiled from:



Settings defined in files that are lower in the list override settings higher.

Reloading settings

You can reload the Settings object at any time by running Settings.reload!.

Reloading settings and config files

You can also reload the Settings object from different config files at runtime.

For example, in your tests if you want to test the production settings, you can:

Rails.env = "production"
  Rails.root.join("config", "settings.yml").to_s,
  Rails.root.join("config", "settings", "#{Rails.env}.yml").to_s,
  Rails.root.join("config", "environments", "#{Rails.env}.yml").to_s

Environment specific config files

You can have environment specific config files. Environment specific config entries take precedence over common config entries.

Example development environment config file:


Example production environment config file:


Developer specific config files

If you want to have local settings, specific to your machine or development environment, you can use the following files, which are automatically .gitignored :

Rails.root.join("config", "settings.local.yml").to_s,
Rails.root.join("config", "settings", "#{Rails.env}.local.yml").to_s,
Rails.root.join("config", "environments", "#{Rails.env}.local.yml").to_s

Adding sources at Runtime

You can add new YAML config files at runtime. Just use:


This will use the given source.yml file and use its settings to overwrite any previous ones.

On the other hand, you can prepend a YML file to the list of configuration files:


This will do the same as add_source, but the given YML file will be loaded first (instead of last) and its settings will be overwritten by any other configuration file. This is especially useful if you want to define defaults.

One thing I like to do for my Rails projects is provide a local.yml config file that is .gitignored (so its independent per developer). Then I create a new initializer in config/initializers/add_local_config.rb with the contents


Note: this is an example usage, it is easier to just use the default local files settings.local.yml, settings/#{Rails.env}.local.yml and environments/#{Rails.env}.local.yml for your developer specific settings.

Embedded Ruby (ERB)

Embedded Ruby is allowed in the configuration files. See examples below.

Accessing Configuration Settings

Consider the two following config files.

  • #{Rails.root}/config/settings.yml
size: 1
  • #{Rails.root}/config/environments/development.yml
size: 2
computed: <%= 1 + 2 + 3 %>
  size: 3
  servers: [ {name:}, {name:} ]

Notice that the environment specific config entries overwrite the common entries.

Settings.size   # => 2
Settings.server # =>

Notice the embedded Ruby.

Settings.computed # => 6

Notice that object member notation is maintained even in nested entries.

Settings.section.size # => 3

Notice array notation and object member notation is maintained.

Settings.section.servers[0].name # =>
Settings.section.servers[1].name # =>

Working with Heroku

Heroku uses ENV object to store sensitive settings which are like the local files described above. You cannot upload such files to Heroku because it's ephemeral filesystem gets recreated from the git sources on each instance refresh.

To use config with Heroku just set the use_env var to true in your config/initializers/config.rb file. Eg:

Config.setup do |config|
  config.const_name = 'AppSettings'
  config.use_env = true

Now config would read values from the ENV object to the settings. For the example above it would look for keys starting with 'AppSettings'. Eg:

ENV['AppSettings.section.size'] = 1
ENV['AppSettings.section.server'] = ''

It won't work with arrays, though.

To upload your local values to Heroku you could ran bundle exec rake config:heroku.



$ appraisal install

Running the test suite

$ appraisal rspec



Config is released under the MIT License.

Something went wrong with that request. Please try again.