Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

Installing and Running Memcached

Install Memcached with apt, Homebrew or Docker, learn the command-line flags that matter (-m, -p, -l, -t, -c), and start a server safely bound to localhost.

Running Memcached is easy: it is a single small program with a handful of flags. This lesson shows how to install it on the common platforms, which options you will actually use, and how to keep it from being exposed to the world by accident.

The commands below are read-only: a web page cannot start a server. Run them in a terminal on your own machine. The interactive blocks in this lesson use a Python helper that explains what the flags mean and how memory is divided.

Installing

On Debian and Ubuntu:

Terminal
sudo apt update
sudo apt install memcached libmemcached-tools
sudo systemctl enable --now memcached

On macOS with Homebrew:

Terminal
brew install memcached
brew services start memcached

With Docker, which works the same on Windows, macOS and Linux:

Terminal
docker run -d --name cache -p 127.0.0.1:11211:11211 memcached:1.6 -m 128

The 127.0.0.1: in front of the port mapping is important: it publishes the port only to your own machine. Without it, Docker listens on every network interface.

There is no official Windows build. On Windows, use Docker Desktop or WSL 2 and install the Linux package inside it.

Check that it is alive:

Terminal
memcached -V
printf 'version\r\nquit\r\n' | nc 127.0.0.1 11211

The server answers VERSION 1.6.x. Port 11211 is the default.

The flags you will use

Flag Meaning Default
-m <MB> Memory for item storage 64
-p <port> TCP port 11211
-l <addr> Address(es) to listen on all interfaces (package configs usually set 127.0.0.1)
-t <n> Worker threads 4
-c <n> Maximum simultaneous connections 1024
-I <size> Largest item size 1 MB
-f <factor> Slab growth factor 1.25
-v / -vv Verbose logging off
-d Run as a daemon off
-U 0 Disable UDP UDP is off since 1.5.6

On Debian-based systems the settings live in /etc/memcached.conf, one flag per line:

TEXT
-m 256
-p 11211
-l 127.0.0.1
-c 1024
-t 4

Run it by hand to experiment:

Terminal
memcached -m 64 -p 11211 -l 127.0.0.1 -vv

How much memory does -m mean?

-m 64 does not mean "64 MB for your data". It is the budget for the item storage, and each item costs more than its value: a small header (key length, flags, expiry, CAS id, pointers for the LRU lists) plus the key itself. The slab allocator also rounds every item up to the size of a chunk in its slab class, so some memory is always wasted. Later chapters cover this in Performance and Sizing; for now remember that you can store fewer items than raw arithmetic suggests.

The helper below estimates how many items fit, assuming a rough 50-byte overhead and a given waste percentage.

Python Estimate how many items fit in -m

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Treat the result as an upper bound, not a promise. You will measure the real number with stats in Stats and Multi-Get.

Keep it private

Memcached's original design assumes a trusted network. There is no login in the default setup, so anyone who can reach port 11211 can read, change or wipe your cache. In 2018 attackers abused servers that were open to the internet with UDP enabled, turning them into amplifiers for huge denial-of-service floods. Since then the defaults are safer, but the rules remain:

  1. Bind to localhost or a private address with -l.
  2. Firewall port 11211 so only your application servers reach it.
  3. Leave UDP off (-U 0).
  4. If you must authenticate, Memcached supports SASL (-S) in builds that include it, or you can put it behind a TLS tunnel or private network.
  5. Never store secrets in the cache that you would not store in a log.
Terminal
# Listen only on the loopback interface and a private address
memcached -l 127.0.0.1,10.0.0.5 -U 0 -m 256

Seeing what the flags do: a simulated start-up

The next block parses a command line the way a person would, and prints the effective configuration. It is a teaching aid, not the real parser.

Python Read a Memcached command line

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Remove -l 127.0.0.1 from the command string and run again to see the warning.

Running it for development

For local development the Docker one-liner is the quickest. Because everything is in RAM, you can stop and start it freely; the cache simply starts empty. Many teams run a 64 or 128 MB instance in development and a larger instance in production. Use the same -I (max item size) in both so a value that fits locally also fits in production.

When something looks wrong, run with -vv. The server prints every command it receives and every response, which makes it a good way to learn the protocol in the next lesson.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which flag sets how much memory Memcached uses for items?

    -m takes a number of megabytes. -p is the port, -t the worker threads and -c the connection limit.
  2. 2. Why should you publish a Docker port as 127.0.0.1:11211:11211?

    Without the 127.0.0.1 prefix, Docker listens on all interfaces and anyone on the network can reach an unauthenticated cache.
  3. 3. What is the default TCP port?

    Memcached listens on 11211 unless you pass -p. 6379 is Redis and 3306 is MySQL.
  4. 4. Does -m 64 let you store 64 MB of raw values?

    Every item has overhead and is rounded up to a slab chunk size, so fewer bytes of values fit than the budget suggests.

Summary

  • Install with apt, brew or Docker; Windows users run it in Docker or WSL.
  • The flags that matter are -m (memory), -p, -l (listen address), -t, -c, -I.
  • -m is a budget for whole items, not just values.
  • Bind to localhost or a private address, firewall the port and keep UDP off.
  • -vv prints every command, a great way to learn.

Next: The Memcached Text Protocol