When does runtime.exs make more sense?

What configs will make sense to put to runtime.exs?

A bit of how I configure apps:

I have generic configs in config/config.exs,
dev-specific parts are in dev.exs,
test-specific - in test.exs,

In dev.exs and test.exs I have some configs set with System.get_env/2… while for Prod environment specific configs go to releases.exs with strict System.fetch_env!/1 so application fails to start if it’s not configured explicitly, and I’m happy with it.

Looks like with runtime.exs I’ll have to use if config_env() == :prod all over the place to switch between System.get_env/2 and System.fetch_env!/1

I only see the case when System.get_env/2 is acceptable in prod as well as in dev/test then probably it would make some sense, but even then defaults for prod and dev sometimes are different.

Surely I’m missing something.


  • releases.exs - runtime configuration for release only
  • #{Mix.env()}.exs - i.e. dev.exs, prod.exs, test.exs - those are compiletime environment-specific configuration files
  • config.exs - compiletime generic configuration file
  • releases.exs - runtime generic configuration file

Please look that machine which compiles code does not needs to run it. When calling System.get_env/1 it’s not executed in some kind of configuration queue, but immediately! This means that machine building code (regardless if it would run it or not) must have specified all environment variables.

Obviously it causes many troubles especially when same project was deployed to multiple machines when each of such machine wanted different environment configuration. It has been partially solved by releases.exs which now should be replaced by more generic runtime.exs.

I recommend to watch this video:

1 Like

My opinion in a nutshell:

If you are on Elixir v1.11, use config/runtime.exs for all configuration by default. Make files like config/runtime_dev.exs as needed and use config_env/0 to check which one to import. (EDIT: Turns out config/runtime.exs doesn’t support imports.) Only move configuration to config/config.exs that you know that you need to set at compile time.

This should give you the easiest path forward as your configuration will behave the same way in dev, test, prod, and release by default.


@Eiji thanks, I saw that video, but looks like I missed one important point:

Should become the main source of config in the long term

This helps to understand the position of core team! Thanks!


Make files like config/runtime_dev.exs as needed and use config_env/0 to check which one to import.

Thank you! I forgot about import_config() function! Now it totally makes sense!

There are two aspects that have been mixed. Env-driven and (compiletime | runtime)-driven file naming.

It appears we move toward the the latter. So in the end we should only have config/compiletime.ex(s?) and config/runtime.exs.

IMHO, Additional *_dev | *_test | *_prod is nice in theory. In practice it’s confusing rather than nicely managed separately.

Finally, with (compiletime | runtime)-driven file naming. Those files are going to be similar to Ruby’s Gemfile where shared config is on the top, then env based groups on the bottom. Though configs can be a lot in a single file, but again IMO, huge single file is pretty much good (same as we’re good with a module has full of documents hundreds of lines).


Note, however, some configuration files, such as config/runtime.exs does not support imports, as they are meant to be copied across systems.

Well that is a silly limitation. If it’s only a policy decision, then I don’t agree with it.

The problem is knowing which files need copying. Unless imported files can be statically determined at buildtime the release won‘t be able to know which config files to include additionally.

1 Like

Ah true, maybe we could just limit it so that the argument must be a string literal. But I can live with it.

I’m not an Elixir core developer, but I guess that we would stay with config/config.exs.

Elixir and Phoenix does not put so much requirements. Unlike Ruby/Rails you can freely create a file my_file.ex containing module MyModule. The only requirement here is that we need to start with something, so the only requirements are:

  • mix.exs
  • config/config.exs
  • config/runtime.exs

Even those are not 100% required as you can write Elixir single file scripts. Also when writing library you don’t have config directory at all.

The rest is up to developers. If you think that config/config.exs is too big you can split it in any way. If you don’t want to do so then simply don’t. All templates generates a generic code. It’s up to you what you would do with it. Nobody stops you from writing whole project by hand without using any generator.

Look that previously we had only config/config.exs and because it causes problems we have now config/runtime.exs. If you do not need runtime-specific configuration nobody forces you to use it.

Well … First of all config/runtime.exs was added mainly for environment-specific configuration, so most probably (except really big projects) we would have just a few simple configuration entries without even checking the environment or just for one environment (like prod-only credentials from system environment). Secondly if there would be a really strong reason for supporting copying of files I would not be surprised if Elixir core team would add an extra project option (for copying files based on pattern) in mix.exs file.

Additional files can be included via an overlay as well, but given it’s documented as not being able to use imports I guess by now the core team seems to not even want to go there.

1 Like