The Redis EXPIRE command sets a timeout on a given key in seconds. After the timeout has expired, the key will be deleted.

Redis also has a PEXPIRE command that works the same as EXPIRE, except that it returns the timeout in milliseconds instead of seconds.

A key with a timeout is said to be volatile in Redis terminology.

Syntax

The syntax goes like this:

EXPIRE key seconds [ NX | XX | GT | LT]

Explanation of arguments:

key	The key for which to set the timeout.
seconds	The number of seconds for the timeout.
NX	Sets an expiry only when the key has no expiry.
XX	Sets an expiry only when the key has an existing expiry.
GT	Sets an expiry only when the new expiry is greater than current one.
LT	Sets an expiry only when the new expiry is less than current one.

The NX, XX, GT, and LT arguments were introduced in Redis 7.0.0.

Example

Suppose we set a key:

SET lunch "Cordon Bleu"

Result:

OK

We didn’t set an expiry for this key, so when I run the TTL command against it:

TTL lunch

Result:

(integer) -1

We get an integer reply of -1 (which means it has no expiry).

Now let’s use EXPIRE to set an expiry:

EXPIRE lunch 86400

Result:

(integer) 1

I got an integer reply of 1, which means it was successful. Here, I set the expiry to 86400 seconds, which is a day. This means that if I want to use the key, I’ll need to do so within 86400 seconds of its expiry being set.

Let’s check its time to live:

TTL lunch

Result:

(integer) 86375

So we still have plenty of time left.

We can also use the EXPIRETIME command to get the absolute Unix time of its expiry.

EXPIRETIME lunch

Result:

(integer) 1655978393

The PEXPIRETIME command does the same thing, but returns the result in milliseconds.

The NX Argument

The NX argument was introduced in Redis 7.0.0.

We can use the NX argument to set the timeout only if the key doesn’t already have an expiry.

To demonstrate this, let’s first try to set the expiry on the key that we used in the previous example:

EXPIRE lunch 100000 NX

Result:

(integer) 0

It doesn’t work. We get an integer reply of 0, which means that the timeout wasn’t set.

Let’s remove the expiry:

PERSIST lunch

Result:

(integer) 1

And try again:

EXPIRE lunch 100000 NX

Result:

(integer) 1

This time we were successful.

Let’s check the time to live:

TTL lunch

Result:

(integer) 99978

Yes, it worked as expected.

The XX Argument

The XX argument was introduced in Redis 7.0.0.

We can use the XX argument to set the timeout only if the key already has an expiry.

Let’s try updating the same key from the previous examples:

EXPIRE lunch 500000 XX

Result:

(integer) 1

Looks like it worked.

Let’s check the current TTL:

TTL lunch

Result:

(integer) 499977

Looks good.

The GT Argument

The GT argument was introduced in Redis 7.0.0.

We can use the GT argument to set the timeout only if the new expiry is greater than current one.

To test this, let’s try updating our key with a smaller timeout:

EXPIRE lunch 400000 GT

Result:

(integer) 0

It didn’t work, because the new expiry is smaller than the current one.

Let’s try again, with a larger expiry:

EXPIRE lunch 499818 GT

Result:

(integer) 1

This time it worked, because our expiry is greater than the current one.

Note that my new expiry is smaller than the 500000 that I had previously used to set the timeout. However, time has elapsed since then, and the time to live has continued to decrease. My new value happened to be higher than the current time to live.

The LT Argument

The LT argument was introduced in Redis 7.0.0.

We can use the LT argument to set the timeout only if the new expiry is less than current one.

To test this, let’s try updating our key with a larger timeout:

EXPIRE lunch 500000 LT

Result:

(integer) 0

It didn’t work, because the new expiry is larger than the current one.

Let’s try again, with a smaller expiry:

EXPIRE lunch 400000 LT

Result:

(integer) 1

This time it worked, because our expiry is less than the current one.