Build Status Coverage Status Code Climate Gem Version security Inline docs

Redlock - A ruby distributed lock using redis.

Distributed locks are a very useful primitive in many environments where different processes require to operate with shared resources in a mutually exclusive way.

There are a number of libraries and blog posts describing how to implement a DLM (Distributed Lock Manager) with Redis, but every library uses a different approach, and many use a simple approach with lower guarantees compared to what can be achieved with slightly more complex designs.

This is an implementation of a proposed distributed lock algorithm with Redis. It started as a fork from antirez implementation.


Redlock works with Redis versions 2.6 or later.


Add this line to your application's Gemfile:

gem 'redlock'

And then execute:

$ bundle

Or install it yourself as:

$ gem install redlock



Usage example

Acquiring a lock

NOTE: All expiration durations are in milliseconds.

  # Locking
  lock_manager =[ "redis://", "redis://", "redis://" ])
  first_try_lock_info = lock_manager.lock("resource_key", 2000)
  second_try_lock_info = lock_manager.lock("resource_key", 2000)

  p first_try_lock_info
  # => {validity: 1987, resource: "resource_key", value: "generated_uuid4"}

  p second_try_lock_info
  # => false

  # Unlocking

  second_try_lock_info = lock_manager.lock("resource_key", 2000)

  p second_try_lock_info
  # => {validity: 1962, resource: "resource_key", value: "generated_uuid5"}

There's also a block version that automatically unlocks the lock:

lock_manager.lock("resource_key", 2000) do |locked|
  if locked
    # critical code
    # error handling

There's also a bang version that only executes the block if the lock is successfully acquired, returning the block's value as a result, or raising an exception otherwise. Passing a block is mandatory.

  block_result = lock_manager.lock!("resource_key", 2000) do
    # critical code
rescue Redlock::LockError
  # error handling

Extending a lock

To extend the life of the lock:

  lock_info = lock_manager.lock("resource_key", 2000)
  while lock_info
    # Critical code

    # Time up and more work to do? Extend the lock.
    lock_info = lock_manager.lock("resource key", 3000, extend: lock_info)
rescue Redlock::LockError
  # error handling

The above code will also acquire the lock if the previous lock has expired and the lock is currently free. Keep in mind that this means the lock could have been acquired and released by someone else in the meantime. To only extend the life of the lock if currently locked by yourself, use the extend_only_if_locked parameter:

lock_manager.lock("resource key", 3000, extend: lock_info, extend_only_if_locked: true)

Redis client configuration

Redlock::Client expects URLs or Redis objects on initialization. Redis objects should be used for configuring the connection in more detail, i.e. setting username and password.

servers = [ 'redis://localhost:6379', => 'redis://someotherhost:6379') ]
redlock =

Redlock works seamlessly with redis sentinel, which is supported in redis 3.2+.

Redlock configuration

It's possible to customize the retry logic providing the following options:

  lock_manager =
                  servers, {
                  retry_count:   3,
                  retry_delay:   200, # milliseconds
                  retry_jitter:  50,  # milliseconds
                  redis_timeout: 0.1  # seconds

It is possible to associate :retry_delay option with Proc object. It will be called every time, with attempt number as argument, to get delay time value before next retry.

retry_delay = proc { |attempt_number| 200 * attempt_number ** 2 } # delay of 200ms for 1st retry, 800ms for 2nd retry, etc.
lock_manager =, retry_delay: retry_delay)

For more information you can check documentation.

Run tests

Make sure you have docker installed.

$ make


This code implements an algorithm which is currently a proposal, it was not formally analyzed. Make sure to understand how it works before using it in your production environments. You can see discussion about this approach at reddit and also the Antirez answers for some critics.


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request