{
  "schema_version": 2,
  "id": "develop/clients/redis-py/scaniter",
  "title": "Scan iteration",
  "url": "https://redis.io/docs/latest/develop/clients/redis-py/scaniter/",
  "summary": "Iterate through results from `SCAN`, `HSCAN`, etc.",
  "tags": [
    "docs",
    "develop",
    "stack",
    "oss",
    "rs",
    "rc",
    "oss",
    "kubernetes",
    "clients"
  ],
  "last_updated": "2026-08-27T15:55:18+01:00",
  "page_type": "content",
  "content_hash": "7e9636766fbe8c3c93420b051abca3f361f967065c459f6fb49452928be1bcde",
  "sections": [
    {
      "id": "content",
      "title": "Content",
      "role": "content",
      "text": "Redis has a small family of related commands that retrieve\nkeys and, in some cases, their associated values:\n\n-   [`SCAN`](https://redis.io/docs/latest/commands/scan) retrieves keys\n    from the main Redis keyspace.\n-   [`HSCAN`](https://redis.io/docs/latest/commands/hscan) retrieves keys and optionally,\n    their values from a\n    [hash](https://redis.io/docs/latest/develop/data-types/hashes) object.\n-   [`SSCAN`](https://redis.io/docs/latest/commands/sscan) retrieves keys from a\n    [set](https://redis.io/docs/latest/develop/data-types/sets) object.\n-   [`ZSCAN`](https://redis.io/docs/latest/commands/zscan) retrieves keys and their score values from a\n    [sorted set](https://redis.io/docs/latest/develop/data-types/sorted-sets) object.\n\nThese commands can potentially return large numbers of results, so Redis\nprovides a paging mechanism to access the results in small, separate batches.\nWith the basic commands, you must maintain a cursor value in your code\nto keep track of the current page. As a convenient alternative, `redis-py`\nalso lets you access the results using an\n[iterator](https://docs.python.org/3/glossary.html#term-iterable).\nThis handles the paging transparently, so you simply need to process\nthe items it returns one-by-one in a `for` loop or pass the iterator\nobject itself in place of a\n[sequence](https://docs.python.org/3/glossary.html#term-sequence).\n\nEach of the commands has its own equivalent iterator. The following example shows\nhow to use a `SCAN` iterator on the Redis keyspace. Note that, as with the `SCAN`\ncommand, the results are not sorted into any particular order, . Also, you\ncan pass `match`, `count`, and `_type` parameters to `scan_iter()` to constrain\nthe set of keys it returns (see the [`SCAN`](https://redis.io/docs/latest/commands/scan)\ncommand page for examples). \n\n[code example]\n\nThe iterators for the other commands are also named with `_iter()` after\nthe name of the basic command (`hscan_iter()`, `sscan_iter()`, and `zscan_iter()`).\nThey work in a similar way to `scan_iter()` except that you must pass a\nkey to identify the object you want to scan. The example below shows how to\niterate through the items in a sorted set using `zscan_iter()`.\n\n[code example]\n\nNote that in this case, the item returned by the iterator is a\n[tuple](https://docs.python.org/3/tutorial/datastructures.html#tuples-and-sequences)\nwith two elements for the key and score. By default, `hscan_iter()`\nalso returns a 2-tuple for the key and value, but you can\npass a value of `True` for the `no_values` parameter to retrieve just\nthe keys:\n\n[code example]"
    }
  ],
  "examples": [
    {
      "id": "content-ex0",
      "language": "py",
      "code": "import redis\n\nr = redis.Redis(decode_responses=True)\n\nr.set(\"key:1\", \"a\")\nr.set(\"key:2\", \"b\")\nr.set(\"key:3\", \"c\")\nr.set(\"key:4\", \"d\")\nr.set(\"key:5\", \"e\")\n\nfor key in r.scan_iter():\n    print(f\"Key: {key}, value: {r.get(key)}\")\n# >>> Key: key:1, value: a\n# >>> Key: key:4, value: d\n# >>> Key: key:3, value: c\n# >>> Key: key:2, value: b\n# >>> Key: key:5, value: e",
      "section_id": "content"
    },
    {
      "id": "content-ex1",
      "language": "py",
      "code": "r.zadd(\"battles\", mapping={\n    \"hastings\": 1066,\n    \"agincourt\": 1415,\n    \"trafalgar\": 1805,\n    \"somme\": 1916,\n})\n\nfor item in r.zscan_iter(\"battles\"):\n    print(f\"Key: {item[0]}, value: {int(item[1])}\")\n# >>> Key: hastings, value: 1066\n# >>> Key: agincourt, value: 1415\n# >>> Key: trafalgar, value: 1805\n# >>> Key: somme, value: 1916",
      "section_id": "content"
    },
    {
      "id": "content-ex2",
      "language": "py",
      "code": "r.hset(\"details\", mapping={\n    \"name\": \"Mr Benn\",\n    \"address\": \"52 Festive Road\",\n    \"hobbies\": \"Cosplay\"\n})\n\nfor key in r.hscan_iter(\"details\", no_values=True):\n    print(f\"Key: {key}, value: {r.hget(\"details\", key)}\")\n# >>> Key: name, value: Mr Benn\n# >>> Key: address, value: 52 Festive Road\n# >>> Key: hobbies, value: Cosplay",
      "section_id": "content"
    }
  ]
}