# facebook/mcrouter: a memcached protocol router for scaling cache tiers

> Mcrouter sits between your application and a fleet of memcached servers, routing keys through a configurable pool graph. It is for teams whose cache has outgrown a single server, and it costs you a second process in the request path.

**facebook/mcrouter** — Mcrouter is a memcached protocol router for scaling memcached deployments.

- Repository: https://github.com/facebook/mcrouter
- Stars: 3,335 · Forks: 554
- Language: C++
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/facebook-mcrouter

## The problem mcrouter solves for a multi-server memcached tier

A single memcached process is easy. The moment you run several, the client has to decide which server owns a key, and every application language ends up reimplementing that decision. Mcrouter moves the decision into a separate process. Applications speak ordinary memcached ASCII to mcrouter, and mcrouter speaks memcached to the real servers behind it. The README describes it as "a memcached protocol router for scaling memcached deployments" and notes it is a core component of cache infrastructure at Facebook and Instagram.

That placement is the whole design. Because mcrouter understands the protocol rather than just proxying bytes, it can do things a client library cannot do cleanly: connection pooling, prefix routing, replicated pools, traffic shadowing, health monitoring with automatic failover, and online reconfiguration. The audience is infrastructure teams running a shared cache tier for many services, where changing routing rules should not require redeploying every caller.

## How routing works: pools, routes and the config string

The unit of configuration is a JSON document with two top-level ideas. A pool is a named list of memcached servers. A route is an expression that says how a request travels through pools. The README's minimal example defines one pool called A with a single server at 127.0.0.1:5001, and a route of PoolRoute|A, which means every key goes to pool A.

Routes compose. The feature list names multiple hashing schemes, prefix routing, replicated pools, broadcast operations, multi-level caches and multi-cluster support, all of which are expressed as route types over pools rather than as code. That is the trade-off worth naming: routing logic becomes declarative and hot-reloadable, but it also becomes a config language you have to learn, and a malformed route is a runtime problem rather than a compile error.

The README also lists destination health monitoring and automatic failover, plus a reliable delete stream. Those are the features that justify the extra process. A client library can hash keys; keeping a dead server out of rotation without a deploy is harder.

## Installing mcrouter on Ubuntu Bionic from the apt package

The README documents a packaged route for Ubuntu Bionic (18.04) amd64 only. You add the repository key, add a sources line, refresh the cache and install. Note that the key step uses apt-key, which is the form the README gives; on newer distributions that command is deprecated, so treat this as a Bionic-era recipe rather than a general one.

```bash
wget -O - https://facebook.github.io/mcrouter/debrepo/bionic/PUBLIC.KEY | sudo apt-key add
```

Then append the repository line to /etc/apt/sources.list:

```bash
deb https://facebook.github.io/mcrouter/debrepo/bionic bionic contrib
```

Refresh and install:

```bash
sudo apt-get update
sudo apt-get install mcrouter
```

After installation, mcrouter --help should print usage. If your distribution is not Bionic amd64, the README points to the wiki installation page instead, and the source build is the path you are on.

## Building from source and running a first request

The source build is a standard autotools flow, but mcrouter depends on folly, wangle, fizz and fbthrift, so the configure step is where most of the work lands. The README's sequence is:

```bash
autoreconf --install
./configure
make
sudo make install
mcrouter --help
```

Once a memcached instance is listening on the local host at port 5001, the README's simplest setup starts mcrouter on port 5000 with an inline config:

```bash
mcrouter \
    --config-str='{"pools":{"A":{"servers":["127.0.0.1:5001"]}},
                  "route":"PoolRoute|A"}' \
    -p 5000
```

A request then goes to mcrouter, not to memcached:

```bash
echo -ne "get key\r\n" | nc 0 5000
```

The README specifies GNU Netcat for that last step. The response you should see is whatever memcached returns for an unknown key, which confirms the route reached the pool.

## Where mcrouter is the wrong tool

The clearest case against it is a single memcached server on the same host as the application. Mcrouter adds a process, a port and a config file to solve a routing problem you do not have. The README's own quick start uses one pool with one server, and that configuration is a demonstration, not a recommendation.

The second limitation is build cost. The README names four Facebook libraries as dependencies, and the packaged install covers only Ubuntu Bionic 18.04 amd64. If you are on a different distribution or architecture, you are in the source-build path with that dependency chain, which is a real operational commitment for a component that sits in front of every cache read.

The third is that mcrouter is a router, not a cache. It does not store anything, so it cannot make a cold cache warm; the feature list includes cold cache warm up, but that is a routing behaviour, not storage. If your problem is cache capacity rather than cache topology, mcrouter does not address it.

## Comparing mcrouter with client-side sharding and twemproxy-style proxies

The most common alternative is client-side consistent hashing: each application library computes the server for a key and connects directly. That removes the extra hop and the extra process, but it puts the server list and the hashing scheme in every service, and changing either means coordinating a deploy across all of them. It also gives you no place to implement shadowing or failover policy.

The other alternative is a thin protocol proxy that only shards. The difference is scope. A thin proxy forwards bytes to one backend; mcrouter's route graph lets a single request fan out to several pools, be replicated, be broadcast, or be shadowed to a second cluster for production traffic testing. The README lists all of those as features. If you only need key-to-server mapping, a thin proxy or client-side hashing is less machinery. If you need the routing behaviours, mcrouter is the one that expresses them in config.

## Maintenance, licensing and what the release history tells you

Mcrouter is MIT licensed, copyright Facebook, Inc. and its affiliates. MIT is permissive: it allows use, modification and redistribution with the licence text retained. That is a summary of the licence identifier, not legal advice; check the LICENSE file for the actual terms.

The repository is not archived, and the last push was on 2026-09-22. The tagged releases are older: v0.41.0-release dates to 2019-11-13, with v0.40.0 in 2019 and v0.39.0 in 2018. That gap matters for planning. If you install from a tagged release, you are on code from 2019. If you build from the main branch, you get current commits but no release notes to read. The README does not document a versioning or upgrade policy, and it does not document rollback. Verify your own upgrade path before you depend on it.

## Conclusion

Adopt mcrouter if you already run more than one memcached server and want hashing, replication and failover controlled by a JSON config instead of application code, and if you can accept an extra hop and a C++ build chain. Do not adopt it for a single local memcached instance, and do not expect the packaged route to cover anything newer than Ubuntu Bionic amd64. Before committing, verify three things: that your config parses under the mcrouter binary you actually installed, that your key distribution matches the hashing scheme you chose, and that your failover behaviour under a dead pool member is what you expect.

## FAQ

### What is mcrouter used for?

It is a memcached protocol router that scales memcached deployments. Applications talk to mcrouter, and mcrouter routes requests to pools of memcached servers, adding hashing, replication, failover and online reconfiguration.

### Is there a Docker image or Kubernetes deployment for mcrouter?

The README does not mention Docker or Kubernetes. It documents an Ubuntu Bionic 18.04 amd64 apt package and a source build using autotools, so container images would be something you build yourself from the source instructions.

### What does an mcrouter config look like?

It is a JSON document with a pools object and a route string. The README's example defines pool A with a single server and route PoolRoute|A, which sends every key to that pool.

### What are mcrouter's dependencies when building from source?

The README lists folly, wangle, fizz and fbthrift as dependencies, and describes the build as a standard autotools flow with autoreconf, configure, make and make install.

### Does mcrouter replace memcached?

No. Mcrouter speaks the memcached ASCII protocol on both sides but does not store data itself; it forwards to memcached servers listed in its pools. You still need memcached running behind it.

## Sources

- [facebook/mcrouter on GitHub](https://github.com/facebook/mcrouter)
- [Issues](https://github.com/facebook/mcrouter/issues)
- [License: MIT](https://github.com/facebook/mcrouter/blob/main/LICENSE)
- [README](https://github.com/facebook/mcrouter/blob/main/README.md)
- [Releases](https://github.com/facebook/mcrouter/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/facebook-mcrouter