# LREM

> Remove occurrences of an element from a list.

URL: https://docs.hotkv.com/commands/lrem/

```
LREM key count element
```

- Group: List
- Complexity: O(N+M) where N is the length of the list and M is the number of elements removed
- HotKV Cloud: all plans
- On-Premise: no license needed

`LREM` removes elements equal to `element` from the list stored at `key`.
`count` controls how many and from which end:

- `count > 0`: remove up to `count` occurrences, scanning from the head.
- `count < 0`: remove up to `|count|` occurrences, scanning from the tail.
- `count = 0`: remove every occurrence.

When the list becomes empty, the key is deleted.

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Success | Integer: the number of elements removed | Same |
| Key does not exist | Integer `0` | Same |

Errors:

- `ERR value is not an integer or out of range` if `count` is not an integer.
- `ERR value is out of range, value must between -9223372036854775807 and 9223372036854775807`
  for a `count` of -9223372036854775808.
- `WRONGTYPE` if `key` holds a value that is not a list.

`count` is checked before the key is looked up.

## Examples

```
127.0.0.1:6379> RPUSH items a b a c a
(integer) 5
127.0.0.1:6379> LREM items -2 a
(integer) 2
127.0.0.1:6379> LRANGE items 0 -1
1) "a"
2) "b"
3) "c"
127.0.0.1:6379> LREM items 0 a
(integer) 1
```

## Compatibility

Same as Redis 7.4 and Valkey 8.

## See also

[LPOS](https://docs.hotkv.com/commands/lpos/index.md), [LTRIM](https://docs.hotkv.com/commands/ltrim/index.md), [LINSERT](https://docs.hotkv.com/commands/linsert/index.md),
[LPOP](https://docs.hotkv.com/commands/lpop/index.md)