Skip to content
Get packs

Guide · Open source

How to use vegeta: install, run a load test and read results

Updated · written with AI from the project's own documentation and checked against our catalogue data

Vegeta is an open-source HTTP load testing tool. You give it a target URL and a request rate, it sends requests at that steady pace, and it reports response times and success rates. This guide shows you how to install it, run your first attack, change the rate and duration, and read the results.

Vegetatsenart/vegeta · ★ 25.2k · MIT

Quick start

  1. 1Install Vegeta. Install it with Homebrew, MacPorts, pacman or pkg, or build it from source using Make and Go.
  2. 2Run a short test. Pipe a GET target into vegeta attack with a short -duration, and send the output to vegeta report.
  3. 3Set your rate. Use -rate to set requests per time unit and -duration to set how long the test runs.
  4. 4Save the results. Use tee results.bin so you can reuse the raw results for other reports.
  5. 5Generate a report. Run vegeta report, or use -type=json or a histogram type for more detail.
  6. 6Create a plot. Run cat results.bin | vegeta plot > plot.html and open the HTML file in a browser.

What Vegeta does and when to use it

Vegeta was built to drill HTTP services with a constant request rate. It works as a command-line program and as a Go library you can call from your own code.

It suits backend developers checking how an HTTP API behaves under a fixed request rate, and teams that want a scriptable, UNIX-style load testing command. It is not aimed at non-HTTP protocols or graphical interfaces, since its documentation covers only HTTP services and command-line and library use.

  • Good fit: HTTP APIs tested at a fixed request rate
  • Good fit: scripted load tests run from a shell
  • Good fit: Go developers embedding load tests in their own programs
  • Not a fit: non-HTTP protocols, or anyone who wants a graphical interface

Install Vegeta on macOS, Arch Linux or FreeBSD

Use your system package manager if you can. On macOS, Vegeta is available through Homebrew or MacPorts. On Arch Linux, use pacman. On FreeBSD, use pkg.

If none of these fit your setup, you can build Vegeta from source. The build needs Make and Go, and the project is cloned with git.

  • Homebrew (macOS)
  • MacPorts (macOS)
  • pacman (Arch Linux)
  • pkg (FreeBSD)
  • Build from source with Make and Go
$ brew update && brew install vegeta $ port install vegeta $ pacman -S vegeta $ pkg install vegeta git clone https://github.com/tsenart/vegeta cd vegeta make vegeta mv vegeta ~/bin # Or elsewhere, up to you.

Run your first load test

The basic workflow is to pipe a target into the attack command, save the output to a file, and pass it to the report command. The tee command keeps a copy in results.bin while the report prints to your terminal.

The attack command sends requests for the duration you set with -duration. Here the test runs for five seconds.

echo "GET http://localhost/" | vegeta attack -duration=5s | tee results.bin | vegeta report

Set the request rate, duration and timeout

The -rate flag sets the number of requests per time unit. The default is 50 per second, and 0 means infinity. The -duration flag sets how long the test runs. Use 0 for an infinite attack.

The actual run time can be longer than the duration because of response delays. The -timeout flag sets the request timeout and defaults to 30s. The -workers flag sets the initial number of workers and defaults to 10.

  • -rate: requests per time unit (default 50/1s)
  • -duration: how long to issue requests (0 = forever)
  • -timeout: request timeout (default 30s)
  • -workers: initial number of workers (default 10)

Read and export results with report, plot and encode

The report command accepts a type flag: text, json, hist with your own buckets, or hdrplot. You can also write the results to a file, which is useful for keeping a record of a run.

The plot command produces an HTML page from the results, and the encode command converts results to csv, gob or json.

  • Text report: vegeta report (default type)
  • JSON metrics: vegeta report -type=json results.bin > metrics.json
  • Histogram: vegeta report -type="hist[0,100ms,200ms,300ms]"
  • HTML plot: cat results.bin | vegeta plot > plot.html
vegeta report -type=json results.bin > metrics.json cat results.bin | vegeta plot > plot.html cat results.bin | vegeta report -type="hist[0,100ms,200ms,300ms]"

Load targets from a file or a generated stream

By default, the attack command reads targets from stdin. The -targets flag points to a file instead. The http format lets you write targets by hand, with method and URL on each line. The json format has one JSON object per line, with method and url required, and suits targets produced by other programs.

The -body flag sets a file whose content is used as the body of every request.

  • http format: one line per request, such as GET http://goku:9090/path/to/dragon?item=ball
  • json format: one object per line, method and url required, body base64 encoded if present
jq -ncM '{method: "GET", url: "http://goku", body: "Punch!" | @base64, header: {"Content-Type": ["text/plain"]}}' | vegeta attack -format=json -rate=100 | vegeta encode

What people use it for

  • Checking how an HTTP API responds at a fixed request rate
  • Running a repeatable load test from a shell script
  • Embedding load tests in a Go program using the library
  • Running distributed load tests across several machines
  • Exporting metrics as JSON for other tools

Frequently asked questions

Is Vegeta free to use?

Yes. Vegeta is released under the MIT licence, as listed on its project page. Check the licence file in the repository for the full terms.

What do I need to install Vegeta?

For package installs you need Homebrew, MacPorts, pacman, or pkg, depending on your system. To build from source you need Make and Go, plus git to clone the repository.

How do I install Vegeta on macOS?

Run brew update && brew install vegeta with Homebrew, or port install vegeta with MacPorts. Both are listed in the README.

Can Vegeta test protocols other than HTTP?

No. The README only describes HTTP services, so it is not documented for other protocols.

What are alternatives to Vegeta?

Comparable projects include k6, wrk, hey and Apache JMeter. This guide does not compare their performance, so test them against your own needs before choosing.

Does Vegeta have a graphical interface?

No. The README describes only command-line and library usage. You get reports and HTML plots from the command line.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Vegeta suits developers and teams who want a scriptable, UNIX-style way to send HTTP load at a fixed rate, or who want to embed load tests in Go code. If you need to test non-HTTP protocols or prefer a graphical interface, or you are not comfortable with the command line, pick a different tool.

Install options & downloads