Difference between Registry.lookup/2 and Process.whereis/1

I’m starting to build more complex apps and I’m slowly reaching for the built-in Registry module. I’ve been reading GenServer — Elixir v1.15.2 a lot. I can feel that there is a lot of depth and subtlety to process registration, but I’m just trying to understand some of the basics first.

Conceptually, Registry.lookup/2 and Process.where/1 seem to serve a similar purpose in that theyboth can resolve an atom representing a named process and yield a PID. But they aren’t the same, e.g.

iex(2)> {:ok, _} = Registry.start_link(keys: :unique, name: Registry.ViaTest)
{:ok, #PID<0.112.0>}
iex(3)> Agent.start_link(fn -> 0 end, name: {:via, Registry, {Registry.ViaTest, :agent1}})
{:ok, #PID<0.115.0>}
iex(4)> Process.whereis(:agent1)

Can someone explain to me why these return different results? I infer that :via provides a kind of “namespace” but I would like more clarity. Thanks for any wisdom!


Yes. Both are registries, but with different capabilities. OTP by default ships with two types of process registries and elixir ships with another one.

  • OTP - Local registry
    • Supplied with name: value
    • Allows only atoms as keys
    • Uniqueness only per node
  • OTP - :global
    • Supplied with name: {:global, value}
    • value key can be any term
    • Uniqueness for the whole cluster
  • Elixir - Registry
    • Supplied with via tuples name: {:via, mod, value}
    • value can be {registry_name, key} or {registry_name, key, value}
    • Uniqueness only per node (if enabled)
    • Supports process registration without unique keys

There are also various third party registries, which also work with via tuples, but might otherwise come with completely different tradeoffs based on their implementations.

Now Process.whereis only integrates with the first listed option - local registration by atom. GenServer.whereis however works with any registry (built in or via tuples). Registry.lookup (and a lot of the other APIs on the module) exist to support more complex and explicit usage of the registry, especially around the non-unique key usecase, which doesn’t integrate with via tuples.


Process.whereis uses the built in, atom based registry that ships with the VM itself. When you give a GenServer (or other OTP process) a name that is a bare atom, the OTP behaviors will use this registry. If you give it a via tuple, it’ll use that other registry.

The difference you get with using the Elixir Registry vs the built in registry is:

  1. Key flexibility: you aren’t limited to atoms.
  2. “namespacing”. Naming with the built in registry can be annoying when you have clusters of processes that you want to be accessible to each other by name, but you need N of those clusters. This also makes testing easier because you can spawn a registry + cluster of processes for each test in parallel.
  3. Other registry features (pubsub, duplicate keys, etc).