Java IntStream: Working with Primitive Streams
Learn how to use Java IntStream for efficient primitive integer processing, covering creation, operations, performance, and common pitfalls.

The examples in this article show how to create and use IntStream for primitive integer processing. You will see the main factory methods, common intermediate and terminal operations, performance trade-offs, and edge cases that can lead to bugs.
What IntStream Is and Why It Exists
IntStream is a primitive specialization of the Stream API for int values, defined in the java.util.stream package. It provides the same functional-style pipeline model as Stream<T>, but operates directly on primitive int data. The main reason it exists is to avoid the boxing and unboxing overhead that occurs when integers are wrapped in Integer objects.
When you write Stream<Integer>, every element is an object reference. Operations like map, filter, and reduce can allocate Integer instances as values move through the pipeline. IntStream avoids that allocation for the common case of processing numeric data, which makes it a good fit for numeric range processing, aggregation, and bulk integer transformations.
Creating an IntStream
There are several ways to obtain an IntStream, and the choice depends on the source of your data.
The most direct approach is IntStream.of, which takes a varargs array of int values:
IntStream values = IntStream.of(3, 1, 4, 1, 5, 9);For sequential integer ranges, range and rangeClosed are the most common factory methods:
IntStream open = IntStream.range(1, 5); // 1, 2, 3, 4
IntStream closed = IntStream.rangeClosed(1, 5); // 1, 2, 3, 4, 5The difference is the upper bound: range excludes it, while rangeClosed includes it. This off-by-one distinction is a frequent source of bugs, so it is worth checking which one your loop logic expects.
If you have an existing int[] array, Arrays.stream gives you an IntStream directly:
int[] numbers = {10, 20, 30, 40};
IntStream stream = Arrays.stream(numbers);For a List<Integer> or another collection, you convert through mapToInt:
List<Integer> list = List.of(5, 10, 15);
IntStream stream = list.stream().mapToInt(Integer::intValue);IntStream.iterate and IntStream.generate produce infinite streams. iterate applies a unary operator to the previous value, while generate calls a supplier for each element. Both require limit to terminate when consumed:
IntStream evens = IntStream.iterate(0, n -> n + 2).limit(10);Intermediate Operations: Transforming the Stream
Intermediate operations are lazy; they do not execute until a terminal operation is invoked. The common ones for IntStream are filter, map, distinct, sorted, limit, and skip.
filter keeps elements that satisfy a predicate:
IntStream evenNumbers = IntStream.range(1, 100)
.filter(n -> n % 2 == 0);map transforms each element into another int:
IntStream squares = IntStream.range(1, 10)
.map(n -> n * n);distinct removes duplicates, and sorted orders the elements. Both are stateful operations. sorted buffers the entire stream, and distinct needs to track seen values, so the memory cost can be significant for large streams.
boxed converts an IntStream into a Stream<Integer>. You need this when you want to collect into a List<Integer> or use operations that only exist on the object stream:
List<Integer> collected = IntStream.range(1, 10)
.boxed()
.collect(Collectors.toList());Without boxed, you cannot call collect with a Collector that expects objects.
Terminal Operations: Producing a Result
A terminal operation triggers the pipeline and produces a result. IntStream provides numeric aggregations that Stream<Integer> does not have directly.
sum, average, min, and max are the most frequently used:
int total = IntStream.range(1, 101).sum();
OptionalDouble avg = IntStream.of(4, 8, 15).average();
OptionalInt min = IntStream.of(4, 8, 15).min();Note that average, min, and max return Optional types because the stream may be empty. sum returns 0 for an empty stream, which is consistent with the identity value of addition.
reduce gives you more control over the aggregation:
int product = IntStream.range(1, 6)
.reduce(1, (a, b) -> a * b);The first argument is the identity value, and the second is an associative accumulation function. The result is 120 for the range 1 through 5.
summaryStatistics collects count, sum, min, average, and max in a single pass:
IntSummaryStatistics stats = IntStream.of(3, 7, 2, 9)
.summaryStatistics();This is useful when you need multiple aggregate values and want to avoid traversing the stream more than once.
toArray produces an int[]:
int[] result = IntStream.range(1, 5).toArray();A Practical Example: Finding Prime Numbers
A realistic use of IntStream is generating prime numbers within a range. The pipeline combines range, filter, and toArray:
int limit = 50;
int[] primes = IntStream.rangeClosed(2, limit)
.filter(n -> isPrime(n))
.toArray();The isPrime helper checks divisibility up to the square root:
private static boolean isPrime(int n) {
return IntStream.rangeClosed(2, (int) Math.sqrt(n))
.noneMatch(d -> n % d == 0);
}This example shows how IntStream composes well: the outer stream filters candidates, and the inner stream tests each candidate for divisibility. The noneMatch terminal operation returns true when no divisor is found.
Performance: Why Primitive Streams Matter
The main performance benefit of IntStream over Stream<Integer> is the elimination of boxing. Boxing an int into an Integer can add allocation pressure and GC work, especially in hot paths or large pipelines. IntStream avoids that by operating directly on primitive int values.
For small collections, the choice is usually not performance-critical. The benefit matters most for large numeric ranges or pipelines with many intermediate operations that would otherwise allocate boxed values.
Parallel streams add another dimension. IntStream.range is well-suited to parallel processing because the range is splittable into contiguous segments. parallel() on a range-based stream can scale across CPU cores for large workloads:
long sum = IntStream.rangeClosed(1, 10_000_000)
.parallel()
.asLongStream()
.sum();Note the asLongStream conversion: summing a large range of int values can overflow int. Using asLongStream avoids that overflow.
Common Pitfalls and Edge Cases
The most common mistake is confusing range with rangeClosed. IntStream.range(1, 10) produces 1 through 9, not 1 through 10. If your loop condition uses <=, you need rangeClosed.
Empty streams are another trap. Calling min() or max() on an empty IntStream returns an empty OptionalInt. Calling getAsInt() on that empty optional throws NoSuchElementException. Always handle the empty case:
OptionalInt max = IntStream.empty().max();
int value = max.orElse(0);Infinite streams must be bounded before a terminal operation consumes them. IntStream.iterate(0, n -> n + 1).sum() would never terminate.
Stateful operations like sorted buffer the entire stream, and distinct must track seen values. In a parallel pipeline, this can negate the memory benefit of using a primitive stream in the first place, because the buffer holds elements before producing output.
Choosing Between IntStream and Traditional Loops
IntStream is not always the better choice. A simple for loop is often more readable for straightforward iteration, especially when you need to break out of the loop early or maintain multiple loop variables.
Use IntStream when:
- You have a pipeline of transformations that would otherwise require nested loops and temporary collections.
- You need aggregate results like sum, average, or statistics.
- You want to parallelize a numeric computation over a range.
- You are already working in a functional style elsewhere in the codebase.
Use a traditional loop when:
- The logic requires early termination with
breakorreturn. - You need to mutate an external variable at each step.
- The iteration order must be explicitly controlled.
- Readability for the team matters more than functional composition.
There is no universal rule. The decision should be based on what the code is doing and how the rest of the codebase expresses similar logic.
Try matching browser tools
All toolsSmall utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Java guides
All Java guidesJava Final Keyword: Usage and Behavior
How Java's final keyword works for variables, methods, and classes, with practical examples and decision guidance for using it.
Java Final Variable: Syntax, Behavior, and Use Cases
Understand what a final variable in Java means, how initialization works, and when to use it for constants, immutability, and clearer code.
Java Duration vs Period: When to Use Each
java duration vs period: Compare Java Duration and Period to handle time-based and date-based calculations correctly. Learn syntax, conversion, and pitfalls.
Instance vs Static Variables in Java: Key Differences
Understand the difference between instance and static variables in Java, including memory, lifecycle, and when to use each.
More in Java
All Java guidesThe guides filed next to this one in Java, in library order.