NumPy arange(): How to Use np.arange() – Real Python (2024)

Providing All Range Arguments

When working with NumPy routines, you have to import NumPy first:

>>> import numpy as np

Now, you have NumPy imported and you’re ready to apply arange().

Let’s see a first example of how to use NumPy arange():

>>> np.arange(start=1, stop=10, step=3)array([1, 4, 7])

In this example, start is 1. Therefore, the first element of the obtained array is 1. step is 3, which is why your second value is 1+3, that is 4, while the third value in the array is 4+3, which equals 7.

Following this pattern, the next value would be 10 (7+3), but counting must be ended before stop is reached, so this one is not included.

You can pass start, stop, and step as positional arguments as well:

>>> np.arange(1, 10, 3)array([1, 4, 7])

This code sample is equivalent to, but more concise than the previous one.

The value of stop is not included in an array. That’s why you can obtain identical results with different stop values:

>>> np.arange(1, 8, 3)array([1, 4, 7])

This code sample returns the array with the same values as the previous two. You can get the same result with any value of stop strictly greater than 7 and less than or equal to 10.

However, if you make stop greater than 10, then counting is going to end after 10 is reached:

>>> np.arange(1, 10.1, 3)array([ 1., 4., 7., 10.])

In this case, you get the array with four elements that includes 10.

Notice that this example creates an array of floating-point numbers, unlike the previous one. That’s because you haven’t defined dtype, and arange() deduced it for you. You’ll learn more about this later in the article.

You can see the graphical representations of these three examples in the figure below:

start is shown in green, stop in red, while step and the values contained in the arrays are blue.

As you can see from the figure above, the first two examples have three values (1, 4, and 7) counted. They don’t allow 10 to be included. In the third example, stop is larger than 10, and it is contained in the resulting array.

Providing Two Range Arguments

You can omit step. In this case, arange() uses its default value of 1. The following two statements are equivalent:

>>> np.arange(start=1, stop=10, step=1)array([1, 2, 3, 4, 5, 6, 7, 8, 9])>>> np.arange(start=1, stop=10)array([1, 2, 3, 4, 5, 6, 7, 8, 9])

The second statement is shorter. step, which defaults to 1, is what’s usually intuitively expected.

Using arange() with the increment 1 is a very common case in practice. Again, you can write the previous example more concisely with the positional arguments start and stop:

>>> np.arange(1, 10)array([1, 2, 3, 4, 5, 6, 7, 8, 9])

This is an intuitive and concise way to invoke arange(). Using the keyword arguments in this example doesn’t really improve readability.

Note: If you provide two positional arguments, then the first one is start and the second is stop.

Providing One Range Argument

You have to provide at least one argument to arange(). To be more precise, you have to provide start.

But what happens if you omit stop? How does arange() knows when to stop counting? In this case, the array starts at 0 and ends before the value of start is reached! Again, the default value of step is 1.

In other words, arange() assumes that you’ve provided stop (instead of start) and that start is 0 and step is 1.

Let’s see an example where you want to start an array with 0, increasing the values by 1, and stop before 10:

>>> np.arange(start=0, stop=10, step=1)array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])>>> np.arange(0, 10, 1)array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])>>> np.arange(start=0, stop=10)array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])>>> np.arange(0, 10)array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

These code samples are okay. They work as shown in the previous examples. There’s an even shorter and cleaner, but still intuitive, way to do the same thing. You can just provide a single positional argument:

>>> np.arange(10) # Stop is 10, start is 0, and step is 1!array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

This is the most usual way to create a NumPy array that starts at zero and has an increment of one.

Note: The single argument defines where the counting stops. The output array starts at 0 and has an increment of 1.

If you try to explicitly provide stop without start, then you’ll get a TypeError:

>>> np.arange(stop=10)Traceback (most recent call last): File "<stdin>", line 1, in <module>TypeError: arange() missing required argument 'start' (pos 1)

You got the error because arange() doesn’t allow you to explicitly avoid the first argument that corresponds to start. If you provide a single argument, then it has to be start, but arange() will use it to define where the counting stops.

Providing Negative Arguments

If you provide negative values for start or both start and stop, and have a positive step, then arange() will work the same way as with all positive arguments:

>>> np.arange(-5, -1)array([-5, -4, -3, -2])>>> np.arange(-8, -2, 2)array([-8, -6, -4])>>> np.arange(-5, 6, 4)array([-5, -1, 3])

This behavior is fully consistent with the previous examples. The counting begins with the value of start, incrementing repeatedly by step, and ending before stop is reached.

Counting Backwards

Sometimes you’ll want an array with the values decrementing from left to right. In such cases, you can use arange() with a negative value for step, and with a start greater than stop:

>>> np.arange(5, 1, -1)array([5, 4, 3, 2])>>> np.arange(7, 0, -3)array([7, 4, 1])

In this example, notice the following pattern: the obtained array starts with the value of the first argument and decrements for step towards the value of the second argument.

In the last statement, start is 7, and the resulting array begins with this value. step is -3 so the second value is 7+(−3), that is 4. The third value is 4+(−3), or 1. Counting stops here since stop (0) is reached before the next value (-2).

You can see the graphical representations of this example in the figure below:

Again, start is shown in green, stop in red, while step and the values contained in the array are blue.

This time, the arrows show the direction from right to left. That’s because start is greater than stop, step is negative, and you’re basically counting backwards.

The previous example produces the same result as the following:

>>> np.arange(1, 8, 3)[::-1]array([7, 4, 1])>>> np.flip(np.arange(1, 8, 3))array([7, 4, 1])

However, the variant with the negative value of step is more elegant and concise.

Getting Empty Arrays

There are several edge cases where you can obtain empty NumPy arrays with arange(). These are regular instances of numpy.ndarray without any elements.

If you provide equal values for start and stop, then you’ll get an empty array:

>>> np.arange(2, 2)array([], dtype=int64)

This is because counting ends before the value of stop is reached. Since the value of start is equal to stop, it can’t be reached and included in the resulting array as well.

One of the unusual cases is when start is greater than stop and step is positive, or when start is less than stop and step is negative:

>>> np.arange(8, 2, 1)array([], dtype=int64)>>> np.arange(2, 8, -1)array([], dtype=int64)

As you can see, these examples result with empty arrays, not with errors.

Parameters and Outputs

Both range and arange() have the same parameters that define the ranges of the obtained numbers:

• start
• stop
• step

You apply these parameters similarly, even in the cases when start and stop are equal.

However, when working with range:

• You have to provide integer arguments. Otherwise, you’ll get a TypeError.
• You can’t specify the type of the yielded numbers. It’s always int.

range and arange() also differ in their return types:

• range creates an instance of this class that has the same features as other sequences (like list and tuple), such as membership, concatenation, repetition, slicing, comparison, length check, and more.
• arange() returns an instance of NumPy ndarray.

Creating Sequences

You can apply range to create an instance of list or tuple with evenly spaced numbers within a predefined range. You might find comprehensions particularly suitable for this purpose.

However, creating and manipulating NumPy arrays is often faster and more elegant than working with lists or tuples.

Let’s compare the performance of creating a list using the comprehension against an equivalent NumPy ndarray with arange():

>>> import timeit>>> n = 1>>> timeit.timeit(f'x = [i**2 for i in range({n})]')>>> timeit.timeit(f'x = np.arange({n})**2', setup='import numpy as np')

Repeating this code for varying values of n yielded the following results on my machine:

These results might vary, but clearly you can create a NumPy array much faster than a list, except for sequences of very small lengths. (The application often brings additional performance benefits!)

This is because NumPy performs many operations, including looping, on the C-level. In addition, NumPy is optimized for working with vectors and avoids some Python-related overhead.

Python for Loops

If you need values to iterate over in a Python for loop, then range is usually a better solution. According to the official Python documentation:

The advantage of the range type over a regular list or tuple is that a range object will always take the same (small) amount of memory, no matter the size of the range it represents (as it only stores the start, stop and step values calculating individual items and subranges as needed). (Source)

range is often faster than arange() when used in Python for loops, especially when there’s a possibility to break out of a loop soon. This is because range generates numbers in the lazy fashion, as they are required, one at a time.

In contrast, arange() generates all the numbers at the beginning.

For more information about range, you can check The Python range() Function (Guide) and the official documentation.