# ZRANGE

> Get members by index, score, or lex range.

Use `ZRANGE` to read a range of members from a sorted set.

By default `<start>` and `<stop>` are zero-based indexes into the ordering, inclusive, and may be negative to count from the end, so `0 -1` returns everything and `0 9` the ten lowest scoring members.

The option that follows changes what those two arguments mean. `BYSCORE` reads them as score bounds, inclusive unless prefixed with `(` and accepting `-inf` and `+inf`. `BYLEX` reads them as member bounds written `[member`, `(member`, `-`, or `+`, which is only meaningful when all members share the same score. `REV` reverses the order, and with `BYSCORE` or `BYLEX` it also means the bounds are given from the higher one to the lower one. `LIMIT <offset> <count>` pages through the result and requires `BYSCORE` or `BYLEX`. `WITHSCORES` includes each member's score.

`ZRANGE` covers everything `ZRANGEBYSCORE`, `ZRANGEBYLEX`, `ZREVRANGE`, and their variants do, and it is the command Redis recommends for new code. Use [`ZRANGESTORE`](/redis/commands/sorted-set/zrangestore) to store the result instead of returning it.

## Syntax

```redis
ZRANGE <key> <start> <stop>
  [BYSCORE | BYLEX]
  [REV]
  [LIMIT <offset> <count>]
  [WITHSCORES]
```

## Arguments

| Argument | Required | Repeatable | Description |
| --- | --- | --- | --- |
| `<key>` | Yes | No | Redis key targeted by the command. |
| `<start>` | Yes | No | Lower bound. Interpreted as a rank by default, as a score with `BYSCORE`, or lexicographically with `BYLEX`. |
| `<stop>` | Yes | No | Upper bound. Interpreted as a rank by default, as a score with `BYSCORE`, or lexicographically with `BYLEX`. |
| `(BYSCORE \| BYLEX)` | No | No | How the two range arguments are read: `BYSCORE` as score bounds (inclusive, or exclusive with a `(` prefix, and `-inf`/`+inf` allowed), `BYLEX` as member bounds (`[member`, `(member`, `-`, or `+`), which only makes sense when every member has the same score. They are zero-based indexes when neither is given. |
| `REV` | No | No | Reverse the result order. |
| `LIMIT <offset> <count>` | No | No | Skip `<offset>` matches and return at most `<count>`; a `<count>` of `-1` returns all remaining. |
| `WITHSCORES` | No | No | Include sorted-set scores. |

## Important points

- Pair-based results may be flattened into one alternating array in RESP2 while RESP3 preserves nested pairs or a map.
- RESP2 represents floating-point reply values as bulk strings; RESP3 may use native double replies. Client libraries commonly decode either form to a language number.

## Response

The reply reports the result of the operation. Error replies have the same shape in RESP2 and RESP3 and are surfaced as exceptions by the SDKs below.

| Protocol | Reply |
| --- | --- |
| RESP2 | Array of members, or flat member/score array with `WITHSCORES` |
| RESP3 | Array of members, or array of member/score pairs with `WITHSCORES` |

<Note>
  Client libraries often decode bulk strings, maps, sets, and numeric strings into language-native values. The table describes the Redis wire reply.
</Note>

## Examples

TCP examples use the TLS `REDIS_URL` from the Upstash console. REST examples use `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`.

<AccordionGroup>

<Accordion title="Redis CLI" icon="terminal">

```bash
ZRANGE my-key 0 -1
```

</Accordion>

<Accordion title="@upstash/redis" icon="node-js" iconType="brands">

```ts
import { Redis } from "@upstash/redis";

const redis = Redis.fromEnv();

await redis.zadd("key",
    { score: 1, member: "m1" },
    { score: 2, member: "m2" },
)
const res = await redis.zrange("key", 1, 3)
console.log(res) // ["m2"]
```

</Accordion>

<Accordion title="upstash_redis" icon="python" iconType="brands">

```python
from upstash_redis import Redis

redis = Redis.from_env()
result = redis.zrange("my-key", 0, -1)
print(result)
```

</Accordion>

<Accordion title="ioredis" icon="node-js" iconType="brands">

```ts
import Redis from "ioredis";

const redis = new Redis(process.env.REDIS_URL!);
const result = await redis.zrange("my-key", "0", "-1");
console.log(result);
```

</Accordion>

<Accordion title="node-redis" icon="node-js" iconType="brands">

```ts
import { createClient } from "redis";

const client = await createClient({ url: process.env.REDIS_URL })
  .on("error", console.error)
  .connect();
const result = await client.zRange("my-key", 0, -1);
console.log(result);
```

</Accordion>

<Accordion title="redis-py" icon="python" iconType="brands">

```python
import os
import redis

client = redis.from_url(os.environ["REDIS_URL"])
result = client.zrange("my-key", 0, -1)
print(result)
```

</Accordion>

<Accordion title="go-redis" icon="golang" iconType="brands">

```go
package main

import (
    "context"
    "fmt"
    "os"

    "github.com/redis/go-redis/v9"
)

func main() {
    opts, err := redis.ParseURL(os.Getenv("REDIS_URL"))
    if err != nil {
        panic(err)
    }
    client := redis.NewClient(opts)
    result, err := client.ZRange(context.Background(), "my-key", 0, -1).Result()
    if err != nil {
        panic(err)
    }
    fmt.Println(result)
}
```

</Accordion>

<Accordion title="jedis" icon="java" iconType="brands">

```java
import java.net.URI;

import redis.clients.jedis.Jedis;

try (Jedis jedis = new Jedis(new URI(System.getenv("REDIS_URL")))) {
  Object result = jedis.zrange("my-key", 0, -1);
  System.out.println(result);
}
```

</Accordion>

<Accordion title="redis-rs" icon="rust" iconType="brands">

```rust
use redis::TypedCommands;

fn main() -> redis::RedisResult<()> {
    let url = std::env::var("REDIS_URL").expect("REDIS_URL is not set");
    let client = redis::Client::open(url)?;
    let mut connection = client.get_connection()?;

    let result = connection.zrange("my-key", 0, -1)?;
    println!("{result:?}");
    Ok(())
}
```

</Accordion>

</AccordionGroup>