progressbar: three Go files, one line, and a spinner when the length is unknown
A really basic thread-safe progress bar for Golang applications
At a glance
- What is it?
- schollz/progressbar is a thread-safe Go progress bar small enough to read in an afternoon, which counts bytes through io.Writer, converts itself into a spinner when the length is minus one, and deliberately refuses to print more than one line.
- Who is it for?
- Adopt schollz/progressbar when you need a progress indicator for a file transfer or a counted loop in a Go program and you want one dependency-light module with a spinner fallback for unknown lengths. Do not adopt it if your output needs several lines, since that is refused by design, or if you need a widget library, a rate limiter or ETA logic beyond what a single bar provides.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 57 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- schollz/progressbar4,707 ★ · +2
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| schollz/progressbar | 4.7k | 4.7k |
2 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The library is three Go files at the repository root
There is no internal/ tree and no packages/ directory. The implementation is the root:
progressbar.go
spinners.go
progressbar_test.goAlongside them sit go.mod, go.sum, LICENSE, a .golangci.yml, a .travis.yml, an examples/ directory and a .github/ directory. The library was written because the author needed a progress bar for croc and everything he tried had problems, which is the most direct provenance statement a small library can carry.
Installing it is one command, and the major version is part of the import path:
go get -u github.com/schollz/progressbar/v3The licence is MIT. The README describes it as a very simple thread-safe progress bar that should work on every OS without problems, and thread safety is stated in the first line rather than buried, which matters for a bar you might advance from a goroutine while a writer feeds it bytes.
Three files also means the whole behaviour is auditable in one sitting, which is the argument for using it over a larger terminal UI library.
A length of -1 turns the bar into a spinner, with no separate type
The unknown-length case is handled inside the bar rather than by a second type. Any bar with length -1 will automatically convert itself into a spinner, and the spinner type is customizable.
That is a small design decision with a large convenience payoff. You do not check whether the server sent a Content-Length header before choosing a widget; you pass the number you have, and if it is -1 the same object animates instead of drawing a fill. The I/O example in the README is explicit about this: it can be run as-is with resp.ContentLength set to -1.
The spinner list itself lives in spinners.go, and the acknowledgments credit briandowns with compiling that list, so the animation frames are borrowed rather than invented.
The examples directory carries the shapes you would otherwise have to invent: a basic bar, a counter, customization, a download with a known length, a download-unknown case, a pacman theme, an ASCII theme and a Unicode theme.
It implements io.Writer, so a download bar is one MultiWriter
The bar counts bytes written to a stream because it implements io.Writer, which means you do not compute progress yourself:
req, _ := http.NewRequest("GET", "https://dl.google.com/go/go1.14.2.src.tar.gz", nil)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
f, _ := os.OpenFile("go1.14.2.src.tar.gz", os.O_CREATE|os.O_WRONLY, 0644)
defer f.Close()
bar := progressbar.DefaultBytes(
resp.ContentLength,
"downloading",
)
io.Copy(io.MultiWriter(f, bar), resp.Body)The mechanism is io.MultiWriter. Every chunk that reaches the file also reaches the bar, and the bar counts it, so the total comes from resp.ContentLength and the description string is passed as the second argument to DefaultBytes.
Two details are worth copying. The file is opened with os.O_CREATE and os.O_WRONLY, so the same code works whether the destination exists. And when the length is unknown, the -1 rule applies here too, because ContentLength is simply passed through.
That is the whole progress story for a transfer: no goroutine, no timer, no reader wrapper.
Customisation is Option functions plus a Theme struct
Everything beyond the defaults goes through NewOptions, which takes a length and a list of options:
bar := progressbar.NewOptions(1000,
progressbar.OptionSetWriter(ansi.NewAnsiStdout()), //you should install "github.com/k0kubun/go-ansi"
progressbar.OptionEnableColorCodes(true),
progressbar.OptionShowBytes(true),
progressbar.OptionSetWidth(15),
progressbar.OptionSetDescription("[cyan][1/3][reset] Writing moshable file..."),
progressbar.OptionSetTheme(progressbar.Theme{
Saucer: "[green]=[reset]",
SaucerHead: "[green]>[reset]",
SaucerPadding: " ",
BarStart: "[",
BarEnd: "]",
}))The example's own comment says k0kubun/go-ansi provides the writer it sets, and go.mod also requires mitchellh/colorstring, chengxilo/virtualterm, golang.org/x/term and rivo/uniseg.
The Theme struct is the interesting part: the five strings set in the example define the bar's shape, so a progress bar does not have to be the shape everyone recognises. The README points at the package documentation for the full option list.
Multi-line output is refused to keep the package OS agnostic
One capability is ruled out in the first paragraph of the README. In order to be OS agnostic, the author does not plan to support multi-line outputs, and the discussion is linked as issue 6.
That is a design constraint rather than a missing feature, which is why it is worth reading the reason. A bar that repaints several lines has to move the cursor up, clear the region below and behave differently on every terminal emulator and console host. A bar that owns exactly one line has none of that to get wrong, which is what the claim of working on every OS rests on.
The cost falls on you. If your program's output already prints a multi-line report and you want the progress inline with it, this is the wrong library, and no option will change that.
The bar width can be set with OptionSetWidth.
Two CI systems, a lint config and a Go 1.25 floor
The repository carries four badges at the top: a GitHub Actions workflow for ci.yml, goreportcard, gocover.io and godoc.org. Underneath there is both a .github/ directory and a .travis.yml, so two continuous integration systems are configured for the same three source files.
Whether both still run is not something the README says, and that is worth knowing before you read anything into the badge. The lint configuration is a .golangci.yml, which is the usual modern choice, sitting next to a Travis file from the older era.
The dependency floor is explicit in go.mod, which declares go 1.25.0 and requires chengxilo/virtualterm, k0kubun/go-ansi, mitchellh/colorstring, rivo/uniseg, stretchr/testify and golang.org/x/term. For a library with three source files that is a real dependency list.
The last push was on 2026-09-19, with v3.19.1 released on 2026-06-30 after v3.19.0 in December 2025 and v3.18.0 in January 2025, so the module path's v3 suffix is current rather than historical.
The thanks list explains which features came from which contributor
The acknowledgments section is a map of how the feature set arrived, and it is more informative than a changelog would be.
Dynom is credited with the massive improvements in version 2.0. CrushedPixel added descriptions and colour code support, which is the OptionSetDescription and OptionEnableColorCodes behaviour in the customisation example. MrMe42 added some minor features, tehstun sent some pull requests, and Benzammour and haseth are credited with helping create v3, the major version the module path carries today.
Then briandowns, who compiled the list of spinners that spinners.go draws from.
Read together, they explain the shape of the API: a bar in early versions, descriptions and colour codes added as options, and a v3 rewrite that the current import path refers to. For a library small enough to read, that history is also a warning: the option names you learn today are the result of several rounds of additions, and the v3 suffix in your import path is there because the earlier APIs were different.
Editorial conclusion
Adopt schollz/progressbar when you need a progress indicator for a file transfer or a counted loop in a Go program and you want one dependency-light module with a spinner fallback for unknown lengths. Do not adopt it if your output needs several lines, since that is refused by design, or if you need a widget library, a rate limiter or ETA logic beyond what a single bar provides. Two things to check before you import it: that your toolchain meets the go 1.25.0 floor in go.mod, and whether you want to set the bar width yourself with OptionSetWidth.
Frequently asked questions
What is schollz/progressbar?
A thread-safe progress bar for Go, MIT licensed, written as three source files at the repository root: progressbar.go, spinners.go and progressbar_test.go. The author built it because he needed one for croc and everything he tried had problems.
How do I install the Go progressbar library?
With go get -u github.com/schollz/progressbar/v3, where the v3 suffix is part of the module path. The go.mod file declares go 1.25.0, so the toolchain has to meet that floor.
How do I add a progress bar to a download in Go?
The bar implements io.Writer, so it counts bytes for you. Pass the response's ContentLength to progressbar.DefaultBytes and copy the body into an io.MultiWriter that writes to both your file handle and the bar, as in the README's example using io.Copy.
What happens when a Go progress bar has no known length?
Any bar created with length -1 automatically converts itself into a spinner, with a customizable spinner type. The README notes the download example can be run that way by setting resp.ContentLength to -1, and the examples directory includes a download-unknown case.
Does schollz/progressbar support multi-line output?
Not by design. The README states the author does not plan to support multi-line output in order to stay OS agnostic, and links issue 6 for the discussion. Everything it draws stays on one line.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/schollz-progressbar)Star history chart for your README
[](https://hysenlabs.com/projects/schollz-progressbar)Was this useful?