> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/grafana/k6/llms.txt
> Use this file to discover all available pages before exploring further.

# Ramping VUs Executor

> Gradually increase or decrease VUs over multiple stages

The `ramping-vus` executor (also known as stages) gradually increases or decreases the number of VUs over defined time periods. This is the most common executor for realistic load testing, as it allows you to simulate traffic patterns that ramp up, sustain, and ramp down.

## How It Works

With ramping VUs:

1. VUs start at `startVUs` (or ramp from 0)
2. VUs increase/decrease linearly to reach each stage's `target`
3. Each stage has a `duration` and `target` VU count
4. VUs continuously run iterations throughout all stages
5. Ramping is smooth and linear between targets

```
VUs ^
100 |          ╱‾‾‾‾‾‾‾‾╲
 75 |        ╱            ╲
 50 |      ╱                ╲
 25 |    ╱                    ╲
  0 |╺━━╯                      ╲___
    +---------------------------------> time
      2m    5m   3m     2m    2m
      (stages)
```

## Configuration

<ParamField path="executor" type="string" required>
  Must be `ramping-vus`
</ParamField>

<ParamField path="startVUs" type="integer" default="1">
  Number of VUs to start with. Can be 0.
</ParamField>

<ParamField path="stages" type="array" required>
  Array of stage objects defining the VU ramping pattern. Each stage must have `duration` and `target`.
</ParamField>

<ParamField path="stages[].duration" type="duration" required>
  Duration of this stage. Can be 0 for instant VU changes.
</ParamField>

<ParamField path="stages[].target" type="integer" required>
  Target number of VUs at the end of this stage.
</ParamField>

<ParamField path="gracefulRampDown" type="duration" default="30s">
  Time to wait for iterations to finish when ramping down VUs. This is separate from `gracefulStop`.
</ParamField>

## Example

### Classic Load Test Pattern

```javascript theme={null}
import http from 'k6/http';
import { sleep } from 'k6';

export const options = {
  scenarios: {
    load_test: {
      executor: 'ramping-vus',
      startVUs: 0,
      stages: [
        { duration: '2m', target: 10 },   // Ramp up to 10 VUs over 2 minutes
        { duration: '5m', target: 10 },   // Stay at 10 VUs for 5 minutes
        { duration: '2m', target: 50 },   // Ramp up to 50 VUs over 2 minutes
        { duration: '5m', target: 50 },   // Stay at 50 VUs for 5 minutes
        { duration: '2m', target: 0 },    // Ramp down to 0 VUs over 2 minutes
      ],
      gracefulRampDown: '30s',
    },
  },
};

export default function () {
  http.get('https://test.k6.io');
  sleep(1);
}
```

### Spike Test

```javascript theme={null}
export const options = {
  scenarios: {
    spike: {
      executor: 'ramping-vus',
      startVUs: 0,
      stages: [
        { duration: '10s', target: 10 },   // Baseline
        { duration: '0s', target: 100 },   // Instant spike to 100 VUs
        { duration: '1m', target: 100 },   // Sustain spike
        { duration: '10s', target: 10 },   // Quick recovery
        { duration: '3m', target: 10 },    // Observe recovery
        { duration: '10s', target: 0 },    // Ramp down
      ],
    },
  },
};
```

### Stress Test - Find Breaking Point

```javascript theme={null}
export const options = {
  scenarios: {
    stress: {
      executor: 'ramping-vus',
      startVUs: 0,
      stages: [
        { duration: '2m', target: 50 },
        { duration: '2m', target: 100 },
        { duration: '2m', target: 150 },
        { duration: '2m', target: 200 },
        { duration: '2m', target: 250 },
        { duration: '2m', target: 300 },
        { duration: '5m', target: 0 },     // Gradual ramp down
      ],
    },
  },
  thresholds: {
    http_req_failed: ['rate<0.1'],       // Less than 10% errors
    http_req_duration: ['p(95)<2000'],   // 95% under 2s
  },
};
```

## When to Use

Use the ramping VUs executor when:

* You want to simulate realistic traffic patterns
* You need to test how your system handles increasing load
* You're performing stress testing to find breaking points
* You want to observe system behavior during ramp-up and ramp-down
* You need to give your system time to warm up before peak load
* You're testing auto-scaling behavior

## Behavior Details

### Linear Ramping

VUs increase/decrease linearly between targets:

```javascript theme={null}
stages: [
  { duration: '60s', target: 60 },
]
// At t=0s:  0 VUs
// At t=10s: 10 VUs
// At t=30s: 30 VUs
// At t=60s: 60 VUs
```

### Zero-Duration Stages

Use `duration: '0s'` for instant VU changes:

```javascript theme={null}
stages: [
  { duration: '1m', target: 10 },
  { duration: '0s', target: 100 },  // Instant jump to 100 VUs
  { duration: '1m', target: 100 },
]
```

### Graceful Ramp Down

When ramping down, VUs get `gracefulRampDown` time to finish their current iteration:

```javascript theme={null}
export const options = {
  scenarios: {
    example: {
      executor: 'ramping-vus',
      startVUs: 100,
      stages: [
        { duration: '5m', target: 100 },
        { duration: '2m', target: 10 },   // Ramping down
      ],
      gracefulRampDown: '30s',  // Each VU has 30s to finish
    },
  },
};
```

### Maximum VUs Reservation

k6 pre-allocates the maximum number of VUs needed across all stages:

```javascript theme={null}
stages: [
  { duration: '1m', target: 50 },
  { duration: '2m', target: 100 },  // Peak: 100 VUs
  { duration: '1m', target: 25 },
]
// k6 will initialize 100 VUs at test start
```

## Common Load Test Patterns

### Soak Test

Sustained load over a long period:

```javascript theme={null}
stages: [
  { duration: '5m', target: 50 },    // Ramp up
  { duration: '3h', target: 50 },    // Soak at 50 VUs for 3 hours
  { duration: '5m', target: 0 },     // Ramp down
]
```

### Breakpoint Test

Continually increase until failure:

```javascript theme={null}
stages: [
  { duration: '5m', target: 100 },
  { duration: '5m', target: 200 },
  { duration: '5m', target: 300 },
  { duration: '5m', target: 400 },
  { duration: '5m', target: 500 },
  // Continue until system breaks...
]
```

### Wave Pattern

Simulate traffic waves:

```javascript theme={null}
stages: [
  { duration: '30s', target: 20 },   // Wave 1 up
  { duration: '30s', target: 10 },   // Wave 1 down
  { duration: '30s', target: 30 },   // Wave 2 up
  { duration: '30s', target: 15 },   // Wave 2 down
  { duration: '30s', target: 40 },   // Wave 3 up
  { duration: '30s', target: 0 },    // Wave 3 down
]
```

## Advanced Configuration

### Multiple Ramping Scenarios

```javascript theme={null}
export const options = {
  scenarios: {
    api_traffic: {
      executor: 'ramping-vus',
      startVUs: 0,
      stages: [
        { duration: '5m', target: 50 },
        { duration: '10m', target: 50 },
        { duration: '5m', target: 0 },
      ],
      exec: 'apiTest',
      tags: { scenario: 'api' },
    },
    web_traffic: {
      executor: 'ramping-vus',
      startVUs: 0,
      startTime: '2m',  // Start 2 minutes later
      stages: [
        { duration: '5m', target: 100 },
        { duration: '10m', target: 100 },
        { duration: '5m', target: 0 },
      ],
      exec: 'webTest',
      tags: { scenario: 'web' },
    },
  },
};

export function apiTest() {
  http.get('https://test.k6.io/api');
}

export function webTest() {
  http.get('https://test.k6.io');
}
```

## Metrics

The executor emits these metrics:

* `iterations` - Total completed iterations
* `iteration_duration` - Time to complete each iteration
* `vus` - Current number of active VUs (changes over time)
* `vus_max` - Maximum number of VUs (from peak stage)

## Validation

<Warning>
  The executor validates that VU targets don't exceed the sanity limit of 100 million VUs.
</Warning>

```javascript theme={null}
// ❌ Invalid - exceeds max VUs
stages: [
  { duration: '1m', target: 100000001 }, // Error!
]

// ❌ Invalid - no stages defined
stages: [] // Error!

// ❌ Invalid - negative target
stages: [
  { duration: '1m', target: -10 }, // Error!
]
```

## Best Practices

1. **Start from zero**: Begin with `startVUs: 0` to see system behavior from cold start
2. **Include ramp-up**: Give your system time to warm up (caches, connection pools, etc.)
3. **Sustain peak load**: Hold peak load long enough to observe steady-state behavior
4. **Gradual ramp-down**: Avoid instant drops to observe system recovery
5. **Set gracefulRampDown**: Allow iterations to complete when ramping down
6. **Monitor throughout**: Watch metrics during all stages, not just peak
7. **Use realistic patterns**: Model actual traffic patterns from your production data

## Comparison with Other Executors

| Feature        | Ramping VUs             | Constant VUs    | Ramping Arrival Rate   |
| -------------- | ----------------------- | --------------- | ---------------------- |
| VU count       | Variable over stages    | Fixed           | Variable (auto-scaled) |
| Complexity     | Medium                  | Low             | High                   |
| Iteration rate | Varies with VUs         | Constant per VU | Fixed (configured)     |
| Best for       | Realistic load patterns | Steady state    | Fixed throughput       |

## See Also

* [Constant VUs](/executors/constant-vus) - Fixed VU count
* [Ramping Arrival Rate](/executors/ramping-arrival-rate) - Variable iteration rate
* [Externally Controlled](/executors/externally-controlled) - Manual VU control via API