Over a million developers have joined DZone.
Refcard #250

Getting Started With Memcached

A high-performance, distributed memory object caching solution.

Written by

James Sugrue Chief Architect, Over-C @sugrue

This new Refcard provides you with basic configuration information for servers and client-side commands to use memcached as a caching solution for your applications. Begin your installation, learn useful commands, and see what tools are available to help monitor and troubleshoot.

Free PDF
Brought to you by Amazon
Section 1


There are four key limitations in memcached to keep in mind:

  1. The key used is a string with a maximum length of 250 bytes
  2. The value has a 1 megabyte size limit, which can be increased with the –I parameter
  3. No persistence
  4. It is not highly available

To install memcached on your Linux-based system, use either of the following commands, depending on the OS that it is being installed to:

  • apt-get install memcached (Debian / Ubuntu)
  • yum install memcached (Red Hat / Fedora)

Once installed you can run memcached using the following command, where –d causes memcached to run as a daemon process:

memcached –p <TCP port> -U <UDP port> -u <username> -d 

Tip: Use memcached –h for up-to-date documentation on the memcached version you have installed on your server

Section 2

Server Configuration

The configuration file for memcached is available at /etc/sysconfig/memcached with defaults set as follows:


The PORT value specified in the above configuration file is the same for TCP and UDP ports.

MAXCONN represents the maximum number of concurrent connections for memcached. Changing it to a higher value is generally ok. Use the stats command to look for the listen_disabled_num attribute. The value for this should be zero. If the number is higher, it indicates that connections have been dropped, and you should then consider increasing the MAXCONN value.

Running multiple instances of memcached on the same server is simply a matter of changing the port that memcached is listening on.

The most straightforward way to connect to memcached and check that it is running ok is to use telnet:

telnet <host> <port>

Commands can be run from this telnet session, as outlined in later sections of this Refcard.

Note that your client-side code must be written to take advantage of memcached; it is not a transparent implementation, and as such, caching is not done automatically on the server-side. Libraries are available for the most popular programming languages so you can use memcached in your application, as can be seen in the following table. The commands outlined in the following sections will be exposed as functions in these libraries.

Language Library Link
Ruby Dalli https://github.com/petergoldstein/dalli
Go gomemcache https://github.com/bradfitz/gomemcache
C/C++ libMemcached http://libmemcached.org/libMemcached.html
Python Pymemcache https://github.com/pinterest/pymemcache
Java Spymemcached https://github.com/couchbase/spymemcached
Node.js Memcached https://github.com/3rd-Eden/memcached
PHP php-memcached https://github.com/php-memcached-dev/php-memcached

Table 1- A selection of memcached client libraries

Section 3

Client Configuration

The typical use case for applications using memcached client libraries is as follows:

  1. Web application requests keys using a client library. The library will calculate key hash values (consistent hashing algorithm is the most common example), and thus determine which memcached server to send the request to
  2. Client library sends parallel requests to all servers identified in the previous step
  3. Responses are sent to the client library from the server

Some client libraries will allow you to apply weight to preferred servers, either by applying a weight value, or by adding that server multiple times to your client configuration. An auto-discovery feature of a memcached client allows you to discover the nodes within the memcached cluster so their IPs do not need to be hardcoded within the application. This is a very useful feature to enable dynamically supported topology changes.

Section 4

Using memcached with MySQL

Paired with MySQL, or another database, memcached can provide an efficient way to access data. The typical usage patterns are:

  • Use MySQL for persistent data and memcached for transient data only
  • Clients read data from memcached, but if there is a cache miss, the client retrieves the data from the MySQL database and then stores the returned value in the cache, for efficient access in subsequent executions

The following attributes are used across a number of the following commands:

Attribute Description
key Name of the unique key that will be used to access the data. Limited to 250 bytes.
flag A 32-bit space stored alongside the main value. Many sub libraries make use of this field, so in most cases it should be avoided, by setting 0 as the flag value.
exptime Expiration time in seconds of the data stored in cache. Use 0 to never expire. Using more than 30 days will be interpreted as a UNIX timestamp for an exact date to expire.
bytes The length in bytes that needs to be allocated for this value.
noreply Optional parameter that ensures no reply is sent from server following command execution.
value Value to be stored, which needs to be provided in a new line following the set command with options.
unique_cas_token A unique token number which can be retrieved using the gets command.

Table 2- Common command attributes used in storage and retrieval

The following commands allow you to add and replace values in your memcached store:

Section 5


Set is the main command that you will use when adding data to your data store, which simply assigns a value to a given key. This command may overwrite existing data. The new items are at the top of the LRU.

set key flags exptime bytes [noreply] value

Section 6


Stores the value provided only if it does not already exist. New items are at the top of the LRU. If an item exists, and the add command fails, the item is placed to the front of the LRU anyway.

add key flags exptime bytes [noreply] value

Section 7


Stores the value provided only if it already exists.

replace key flags exptime bytes [noreply] value

Section 8


Add this value after the last byte in an existing item. If the specified key does not exist, the command will fail.

append key flags exptime bytes [noreply] value

Section 9


Prepend this value before the first byte in an existing item. If the specified key does not exist, the command will fail.

prepend key flags exptime bytes [noreply] value

Section 10


Stored data but only if no one else has updated the data since you read it last. Abbreviation for “Check And Set” (or “Compare And Swap”). This command is useful to resolving race conditions on updating cache data. If the unique_cas_token for the item has changed since you last retrieved it (using gets) it will not be stored.

cas key flags exptime bytes unique_cas_token [noreply] value

The following commands allow you to retrieve values from your memcached store.

Section 11


Command for retrieving data for a given key, or set of keys. If a key does not exist, no value is returned.

get key [key2 ..keyn]

Section 12


Get command to be used with CAS, which returns the unique_cas_token with the item. ICommand for retrieving data for a given key, or set of keys. If a key does not exist, no value is returned.

gets key [key2 ..keyn]

Section 13


Removes an item from the cache if it exists.

delete key [noreply]

Section 14


These commands will either increment or decrement the numeric value of an existing key. These commands will only succeed where the key is a numeric value.

incr key increment_value

decr key decrement_value

Section 15


Invalidates all cache items in your memcached server. This command takes an optional time parameter, which allows you to instruct memcached to clear this data after a number of seconds.

Flush_all [time]

The following commands allow you to inspect settings on the memcached server. Stats commands give some insights on how performance of your setup could be tuned, as well as monitoring the overall usage of the cache.

Section 16


The basic stats command which returns values for server uptime, memcached version, number of connections, number of items, and other traffic-related statistics.

Section 17

stats items

Returns information about items stored in memcached, broken down by slab id. Returns values for items, age, cache eviction.


Section 18

stats slabs

Returns information about items stored in memcached, broken down by slab id. Values returned in this command are more focused around performance such as memory usage, allocated memory, and number of free chunks.

stats slabs 

Section 19

stats sizes

Illustrates how items would be distributed if broken into 32 byte buckets instead of your current number of slabs, helping you to determine how efficient your slab sizing is.

stats sizes 

Although some level of debugging is possible using the commands listed above with the telnet client, there are a number of other tools available to help monitor and troubleshoot your distributed memcached setup. The following is a summary of the most popular tools:

Section 20


Link: https://code.google.com/archive/p/memcache-top/

Command line tool that displays real-time stats from memcached, displaying the results in a view similar to top. This tool can only monitor a single memcached instance at a time. Results include I/O throughput and evictions per second along with gets and sets per second.

Section 21


Link: https://blog.elijaa.org/phpmemcachedadmin-download/

A standalone web-based application that displays memcached stats, including details on server slabs, memory wasted, and item key values. You can execute commands on a memcached server from this interface. Allows the monitoring of multiple memcached instances.

Section 22


Link: https://github.com/memcached-manager/memcached-manager

A single-page Sinatra memcached manager/admin that allows you to read stats, view, edit, and create keys from memcached. Can easily be plugged into a Rails/Rack app and can work with multiple instances of memcached.

Replication is not supported out-of-the-box in memcached, as it is designed to be a transient cache store. However, replication can be achieved through some third-party solutions.

Section 23


Link: https://github.com/ignacykasperowicz/repcached

Repcached allows you to have a redundant memcached installation running on another server. This is done by applying a patch that adds a new –x parameter, which accepts the IP address of the other server. Note that each server will need to have a link to the other.

Section 24


Link: http://cybozu.github.io/yrmcds/

Developed mainly for session storage, yrmcds (Ymmt’s Replicatin MemcacheD for Sessions) is completely compatible with memcached, and as such, can be used as a drop-in replacement. To enable replication, a virtual IP address needs to be specified along with the configuration of clustering software such as keepalived.

Section 25


Link: https://github.com/twitter/twemproxy

A lightweight proxy for memcached as well as Redis, built by Twitter to reduce the number of open connections to cache servers. Requests to a pool of memcached instances go through this proxy. Using two twemproxy instances, traffic can be directed to both a pool of slaves, as well as a pool of master instances.

Following these best practices will help you get the most from memcached:

  1. From stats, take note of the evictions count, which shows the number of non-expired items that were removed from the cache to make space for new items. If this number is high, it indicates that the memory allocated for items storage is too low.
  2. The default number of threads is 4, and for most cases should not be changed. Using a single thread will be too slow, and more than 8 threads can lead to high lock contention.
  3. Retrieve values in bulk when possible rather than doing a number of get calls in series.
  4. Compressing large values will speed up your application as there is less data being transmitted over the wire, and less memory being used when storing the value in memcached. Most clients support enabling or disabling compression using either an item size threshold or even on a per-item basis.
  5. When initializing memcached, you can prepopulate the cache with keys, meaning your application will have less cache misses in its initial execution after a redeploy on the server.

The ports on which your memcached instances are running should not be exposed to the internet as a rule. Since version1.4.3, SASL (Simple Authentication and Security Layer) is included. Note that SASL restricts access to the daemon but does not hide communications.

Tip: Enable SASL on memcached by using the –S flag on startup. Following this, all commands require that authentication be successful before they are issued on a connection.

To increase your memcached security beyond SASL, the following should be considered:

  • Never run memcached as root. If someone did gain access to memcached and there was a security vulnerability, then they would be able to compromise your machine and network.
  • Use a firewall to limit which connections are open to the outside world. If you are running memcached on a single server, then you can bind the instance to localhost using the –l parameter, restricting cache access to just that machine.


  • Featured
  • Latest
  • Popular
Design Patterns
Learn design patterns quickly with Jason McDonald's outstanding tutorial on the original 23 Gang of Four design patterns, including class diagrams, explanations, usage info, and real world examples.
217.4k 656.9k
Core Java
Gives you an overview of key aspects of the Java language and references on the core library, commonly used tools, and new Java 8 features.
138k 384.9k
Getting Started with Git
This updated Refcard explains why so many developers are migrating to this exciting platform. Learn about creating a new Git repository, cloning existing projects, the remote workflow, and more to pave the way for limitless content version control.
136.6k 310.8k
Getting Started with Ajax
Introduces Ajax, a group interrelated techniques used in client-side web development for creating asynchronous web applications.
103.4k 218.9k
Foundations of RESTful Architecture
The Representational State Transfer (REST) architectural style is a worldview that elevates information into a first-class element of architectures. REST allows us to achieve the architectural properties of performance, scalability, generality, simplicity, modifiability, and extensibility. This newly updated Refcard explains main HTTP verbs, describes response codes, and lists libraries and frameworks. It also gives additional resources to further explore each topic.
110.6k 193.2k
Scrum is a framework that allows people to productively and creatively deliver products of the highest possible value. With over 70% of Agile teams using Scrum or Scrum hybrid, learn more about its benefits in managing complex product development. This newly updated Refcard explores the details of Scrum, including theory, values, roles, and events. It also includes a sample of a popular approach to deliver Integrated Increments in a scaled environment.
99.3k 266.2k
Spring Configuration
Catalogs the XML elements available as of Spring 2.5 and highlights those most commonly used: a handy resource for Spring context configuration.
106.2k 276.3k
Core CSS: Part I
Covers Core principles of CSS that will expand and strengthen your professional ability to work with CSS. Part one of three.
92.5k 204.8k
jQuery Selectors
Introduces jQuery Selectors, which allow you to select and manipulate HTML elements as a group or as a single element in jQuery.
95k 364.9k
Core Java Concurrency
Helps Java developers working with multi-threaded programs understand the core concurrency concepts and how to apply them.
93.7k 209.7k
Getting Started with Eclipse
Eclipse IDE is a cross-platform, multi-purpose, open-source Integrated Development Environment. It is widely used to develop projects in Java, JavaScript, PHP, C++, Scala, and many others. This newly updated Refcard breaks down installing, setting up, and getting started with Eclipse. It also covers productivity tips, creating new projects and files, accessing Source Control Managers, and debugging configurations.
84.2k 231.8k
Core CSS: Part II
Covers Core principles of CSS that will expand and strengthen your professional ability to work with CSS. Part two of three.
75.4k 145.3k
{{ card.title }}
{{card.downloads | formatCount }} {{card.views | formatCount }}

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}