How Does range() Work in Python?

range() produces a sequence of numbers, and it comes in three forms. With one argument it counts from zero. With two arguments it counts from the start up to, but not including, the stop value. With three arguments it also takes a step, and that step may be negative.

print(list(range(5)))          # [0, 1, 2, 3, 4]
print(list(range(2, 6)))       # [2, 3, 4, 5]
print(list(range(2, 10, 3)))    # [2, 5, 8]
print(list(range(5, 0, -1)))    # [5, 4, 3, 2, 1]
print(list(range(10, 0, -3)))   # [10, 7, 4, 1]

The most important detail is that the stop value is never included. range(5) is five numbers that start at zero and not six, and range(2, 6) is 2, 3, 4, and 5. This is the opposite of slicing, where the stop index is included, and mixing the two up is a classic off-by-one mistake.

The step argument can be any integer except zero. A positive step counts upward and a negative step counts downward. In the negative case the start has to be greater than the stop, or the range is empty, so range(0, 5, -1) produces nothing at all.

Two more details are worth knowing. range accepts any integers and not only literal numbers, so range(len(items)) is the standard way to produce the indexes of a list. And range is happy with very large values, because it does not build them. range(10 ** 18) is created instantly and takes no meaningful memory, which is the subject of the next answer.

Since Python 3, range() returns a range object, and that object is lazy. It works out its numbers as they are needed instead of storing them all, so the amount of memory it uses does not depend on how many numbers it covers.

import sys

r = range(1000000)
print(type(r).__name__)      # range
print(len(r))                 # 1000000
print(sys.getsizeof(r))       # 48 - a tiny fixed-size object
print(r[0], r[-1])            # 0 999999

# The same numbers as a list: the range object is tiny, the list is not.
materialised = list(r)
print(sys.getsizeof(materialised))   # 8000056 bytes

# It still behaves like a sequence.
print(list(r[:5]))             # [0, 1, 2, 3, 4]
print(999999 in r)              # True

The range object occupies 48 bytes no matter how many numbers it covers, because it stores only three numbers, which are the start, the stop, and the step, plus a little extra bookkeeping. The materialised list of the same million integers needs about eight million bytes, and that figure does not even count the integer objects themselves, which take a large allocation of their own.

Even though the range object is lazy, it still supports len, indexing, slicing, containment tests, and iteration, because it implements the sequence protocol. Membership testing is the one exception, because 999999 in r is answered with arithmetic instead of a scan, so it stays fast even for a very long range.

This is why range replaced the old Python 2 xrange, and it is a good example of the general idea that Python 3 prefers lazy sequences for exactly this reason. The same thinking applies to the generators returned by zip, map, and filter, and to itertools.count, which is the version of range without an upper limit.

range() takes up to three arguments. range(stop) produces the numbers from zero up to, but not including, the stop value. range(start, stop) produces the numbers from the start up to, but not including, the stop value. range(start, stop, step) does the same with a fixed step between the values, and that step may be negative so that the numbers count downward.

The stop value is never included. range(5) is 0, 1, 2, 3, and 4, which is five numbers and not six. This matches the half-open interval idea that is used in slicing and in most programming languages, and it exists so that a range can be used directly as an index into a sequence of the same length. for i in range(len(items)) is therefore always safe.

All three arguments have to be integers, or more precisely they have to support the index protocol. A float raises a TypeError, and that is worth remembering because a computed value such as len(items) / 2 produces a float in Python 3. You need to write // instead, or wrap the result in int().

Since Python 3, range also accepts keyword arguments, so range(stop=5) and range(start=1, stop=5, step=2) both work, which is unusual for a built-in function.

Two related facts round out the answer. range returns a range object rather than a list, so it is lazy and it takes the same amount of memory however long it is. And when you want a counter with no upper limit at all, itertools.count() does that job.