Why keyword lists for opts instead of maps?

I’m sure this has been asked elsewhere (but forgive me I could not find something that addressed this specifically)…

Why do Elixir functions usually take keyword lists as options? Why not maps? Keyword lists are problematic especially if you’d like to pattern match on a map key to route to different functions, for example. Is there a historical or performance-based reason why keywords are used over maps?


Maybe not an exhaustive list, but some reasons:

  • Erlang historically uses proplists. Not 100% the same but similar.
  • The keyword syntax does have some nice sugar
  • Elixir used to have HashDict instead of maps, so keyword lists might have been supported before maps were

Elixir keyword lists are strict subset of proplists.

This could be done for maps as well TBH.

My reasons:

  • Maps are way younger than property lists/keyword lists
  • Keyword lists allow for duplicated keys which can be useful sometimes

This is worth highlighting, it gives you a CLI-repeated-flag-like interface for options.


Joining the last two. I’d prefer maps any day for config but prioritising the last given config key is impossible with maps.

I do however do my best to only use maps for config in my internal projects.


I find using keyword lists with Keyword.get/3 very handy because you can easily define a default value. Might be somehow possible with Maps too, I guess.

1 Like


Though as others already have said, the big plus of KW is that it enables for having a key multiple times, and they are also ordered…

Try ecto with maps instead of KW… You won’t have much joy…


Yep, I think it’s a mix of historical and practical reasons (the latter including possibility of duplicated keys, and explicit ordering).

You are right that keyword lists are more inconvenient when using pattern matching. But then again, I think they make a good outside interface, and usually I validate and parse options into another data structure (like a map or struct) as soon as they get within the boundary of my module or library.


Keyword lists are very core to the Elixir syntax itself. For example

def the_answer do

is syntax sugar for

def the_answer, do: 42

or even

def(the_answer, [do: 42])

which is basically 2 parameters passed to the def macro. The last one is a keyword list with a :do key in it.

This is why all your functions can take a keyword list without square braces as the last parameter – because the core language syntax uses that.


Maps weren’t introduced until OTP 17.0 in 2014, and were experimental until at least 2015.


Personally, I like KW lists because of a) order, b) syntactic sugar.

foo( bar, a: 1, b: 2, c: 3) 

is so much nicer than:

foo( bar, %{ a: 1, b: 2, c: 2})

When I need accessing the options in a map-like fashion, I’m willing to pay the price of having the KW list converted to a map in my function.

Besides, maybe what you sometimes need is precisely a list-like pattern matching e.g.:

def foo( bar, [ a: 1 | [ b: 2 | _]] = opts)
1 Like

Elixir had an option to choose either keyword lists and maps for options. The reason why we chose keyword lists are because they preserve user ordering and they allow duplicate keys. We use both features in Elixir itself.

For example, in try/catch/after, we warn if you put after before catch, as that would read weird. Using maps would not allow us to warn in those cases, as you always have alphabetical ordering.

When you do import Keyword, only: [get: 2, get: 3], those are duplicate keys. Keyword.__info__(:functions) returns duplicate keys too.

In other words, there are scenarios where keyword lists can be useful and unifying opts under keyword lists is reasonable. Community projects, such as Ecto, leverages them too. Plus other benefits such as Erlang compat.


i’m interested, could you elaborate please

ectos DSL relies on the fact that you can use keyword lists more than one time.

1 Like