How to Use the Redis SETNX Command

Have a Database Problem? Speak with an Expert for Free
Get Started >>


When you’re using Redis to store data in key-value pairs, it’s important to know how to set a value at a particular key. Depending on the circumstances, you may not want to set the value if it would overwrite an existing value at the key. Fortunately, you can use the Redis SETNX command to handle these situations– this command only sets a value at a key if the key doesn’t already exist. In this article, we’ll discuss the SETNX command and look at some examples of its use.


Before proceeding with this tutorial, make sure that you have a Redis database running on your machine. It needs to be installed and configured properly. You can check the version number of your Redis installation by using the command redis-server --version.

The Redis database

Redis can be defined as an open source in-memory data store. It’s written in ANSI C and works with a variety of operating systems: Linux, MacOS, BSD and more. Redis can be used as a database, but it can also function as a cache or a message broker. A number of data types are supported within Redis: strings, sets, lists, sorted sets, hashes and many more.

While Redis provides many commands to manipulate and access data in its key-value store, this tutorial will focus on the SETNX command, which is used to set a string value at a key if the key doesn’t already exist in your Redis environment.

The Redis command-line interface

Redis provides an interactive terminal, redis-cli, that is used to execute different commands. This simple software runs on the terminal, where it receives commands from the user and then submits them to Redis. The commands are transferred to the server, which produces an output. You can determine the version of this command-line interface by using the command redis-cli --version.

To start up an instance of redis-cli and test the interface, you can execute the following command:

redis-cli PING

The expected output should return PONG.

Here’s another simple example:

redis-cli set count "5"

This command will set the key value count as a string that represents the integer 5.

You can use the command to increase the value of count:

redis-cli incr count

NOTE: This command should return a value of 6 because we have used the incr command to increase count by one.

The command SETNX in Redis

As we mentioned earlier, the Redis SETNX command is used to set a string value at a given key. The term SETNX is an abbreviation of the phrase “setting the key if not exists”; thus, the command will not run if the key value already exists in Redis.

A good example is shown below:

2> SETNX greetings "Welcome!"
(integer) 1

Here’s another example of the command:

2> SETNX site "ObjectRocket"
(integer) 1

The first argument is the name of the command in Redis, the second is the name of the key, and the third one is the value of the key.

If we use the GET command after our SETNX examples, it will return output like the following:

4> GET greetings
"Welcome!"> GET site

If the SETNX command executed successfully, you’ll receive an output of 1; otherwise, a value of 0 will be returned if the key already exists.:

4> SETNX greetings "Hello!"
(integer) 0> SETNX site "ObjectRocket"
(integer) 0

Implement a distributed lock using SETNX

A lock ensures that you have sole access to the data and can carry out your activities until you release it to others. In some cases, it would be helpful for various systems to to able to work using shared resources in a mutually exclusive manner. You can use the SETNX command to enable this type of distributed lock:

SETNX lock


When you’re setting a value at a key in Redis, you may not want to overwrite any value that might already exist at the key. In these situations, the SETNX command can be used. This command ensures that a value will only be set at a key if that key doesn’t exist. In this article, we learned how the Redis SETNX command works and looked at some examples to understand how it’s used. If you’ve been following along with our examples, you’ll be ready to make use of the SETNX command in your own Redis work.

Pilot the ObjectRocket Platform Free!

Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.

Get Started

Keep in the know!

Subscribe to our emails and we’ll let you know what’s going on at ObjectRocket. We hate spam and make it easy to unsubscribe.