{ "schema_version": 2, "id": "commands/xtrim", "title": "XTRIM", "url": "https://redis.io/docs/latest/commands/xtrim/", "summary": "Deletes messages from the beginning of a stream.", "since": "5.0.0", "tags": [ "docs", "develop", "stack", "oss", "rs", "rc", "oss", "kubernetes", "clients" ], "last_updated": "2026-07-24T11:07:00+02:00", "page_type": "content", "content_hash": "dbc9c7cbce34924a1ce991b1e7ca238db472e97b2da809e766ba223143f85cbb", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "`XTRIM` trims the stream by evicting older entries (entries with lower IDs) if needed." }, { "id": "required-arguments", "title": "Required arguments", "role": "content", "text": "
\nkey\n\nThe name of the stream key.\n
\n\n
\nMAXLEN | MINID\n\nThe trimming strategy:\n- `MAXLEN`: Evicts entries as long as the stream's length exceeds the specified threshold\n- `MINID`: Evicts entries with IDs lower than the specified threshold (available since Redis 6.2.0)\n
\n\n
\nthreshold\n\nThe trimming threshold:\n- For `MAXLEN`: `threshold` is a non-negative integer specifying the maximum number of entries that may remain in the stream after trimming. Redis enforces this by removing the oldest entries - that is, the entries with the lowest stream IDs - so that only the newest entries are kept.\n- For `MINID`: `threshold` is a stream ID. All entries whose IDs are less than `threshold` are trimmed. All entries with IDs greater than or equal to `threshold` are kept.\n
" }, { "id": "optional-arguments", "title": "Optional arguments", "role": "parameters", "text": "
\n= | ~\n\nThe trimming operator:\n- `=`: Exact trimming (default) - trims to the exact threshold\n- `~`: Approximate trimming - more efficient, may leave slightly more entries than the threshold\n
\n\n
\nLIMIT count\n\nLimits the number of entries to examine during trimming. Available since Redis 6.2.0. When not specified, Redis uses a default value of 100 * the number of entries in a macro node. Specifying 0 disables the limiting mechanism entirely.\n
\n\n
\nKEEPREF | DELREF | ACKED\n\nSpecifies how to handle consumer group references when trimming. If there are no consumer groups, these arguments have no effect. Available since Redis 8.2.\n\nIf no option is specified, `KEEPREF` is used by default. Unlike the `XDELEX` and `XACKDEL` commands where one of these options is required, here they are optional to maintain backward compatibility:\n\n- `KEEPREF` (default): When trimming, removes entries from the stream according to the specified strategy (`MAXLEN` or `MINID`), regardless of whether they are referenced by any consumer groups, but preserves existing references to these entries in all consumer groups' PEL (Pending Entries List).\n- `DELREF`: When trimming, removes entries from the stream according to the specified strategy and also removes all references to these entries from all consumer groups' PEL.\n- `ACKED`: When trimming, only removes entries that were read and acknowledged by all consumer groups. Note that if the number of referenced entries is larger than `MAXLEN`, trimming will still stop at the limit.\n
\n\nFor example, this trims the stream to exactly the latest 1000 items:\n\n[code example]\n\nIn this example, Redis evicts all entries that have an ID lower than 649085820-0:\n\n[code example]\n\nBy default, or when you provide the optional `=` argument, the command performs exact trimming.\n\nDepending on the strategy, exact trimming means:\n\n* `MAXLEN`: The trimmed stream's length will be exactly the minimum between its original length and the specified `threshold`.\n* `MINID`: The oldest ID in the stream will be exactly the maximum between its original oldest ID and the specified `threshold`.\n\nNearly exact trimming\n---\n\nBecause exact trimming may require additional effort from the Redis server, you can provide the optional `~` argument to make it more efficient.\n\nFor example:\n\n[code example]\n\nThe `~` argument between the `MAXLEN` strategy and the `threshold` means that you are requesting to trim the stream so its length is **at least** the `threshold`, but possibly slightly more.\nIn this case, Redis stops trimming early when performance can be gained (for example, when a whole macro node in the data structure can't be removed).\nThis makes trimming much more efficient, and it is usually what you want, although after trimming, the stream may have a few tens of additional entries over the `threshold`.\n\nAnother way to control the amount of work done by the command when using `~` is the `LIMIT` clause.\nWhen you use it, it specifies the maximum `count` of entries that will be evicted.\nWhen you don't specify `LIMIT` and `count`, Redis implicitly uses the default value of 100 * the number of entries in a macro node as the `count`.\nSpecifying the value 0 as `count` disables the limiting mechanism entirely." }, { "id": "examples", "title": "Examples", "role": "example", "text": "redis> XADD mystream * field1 A field2 B field3 C field4 D\n\"1784722085136-0\"\nredis> XTRIM mystream MAXLEN 2\n(integer) 0\nredis> XRANGE mystream - +\n1) 1) \"1784722085136-0\"\n 2) 1) \"field1\"\n 2) \"A\"\n 3) \"field2\"\n 4) \"B\"\n 5) \"field3\"\n 6) \"C\"\n 7) \"field4\"\n 8) \"D\"" }, { "id": "redis-software-and-redis-cloud-compatibility", "title": "Redis Software and Redis Cloud compatibility", "role": "content", "text": "| Redis
Software | Redis
Cloud | Notes |\n|:----------------------|:-----------------|:------|\n| ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | |" }, { "id": "return-information", "title": "Return information", "role": "returns", "text": "**RESP2:**\n\n[Integer reply](../../develop/reference/protocol-spec#integers): The number of entries deleted from the stream.\n\n**RESP3:**\n\n[Integer reply](../../develop/reference/protocol-spec#integers): The number of entries deleted from the stream." } ], "examples": [ { "id": "optional-arguments-ex0", "language": "plaintext", "code": "XTRIM mystream MAXLEN 1000", "section_id": "optional-arguments" }, { "id": "optional-arguments-ex1", "language": "plaintext", "code": "XTRIM mystream MINID 649085820", "section_id": "optional-arguments" }, { "id": "optional-arguments-ex2", "language": "plaintext", "code": "XTRIM mystream MAXLEN ~ 1000", "section_id": "optional-arguments" } ] }