shopspring/decimal: the zero value is 0 and every method returns a new value
Arbitrary-precision fixed-point decimal numbers in Go
At a glance
- What is it?
- shopspring/decimal is a small Go library for arbitrary-precision fixed-point numbers, built for money and totals: exact addition, subtraction and multiplication, division at a precision you choose, and serialization through database/sql, JSON and XML. Its two design decisions are deliberate and both cost something. The zero value is usable without initialization, and every method allocates a new value instead of mutating in place.
- Who is it for?
- Use it wherever rounding errors would reach a customer: prices, tax, fees, invoice splits, anything persisted to a column a human reads. Do not use it in a hot numeric loop, because every method allocates, and switch to one of the alternatives the README lists if you need speed at lower precision.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 14 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
- shopspring/decimal7,519 ★ · +37
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| shopspring/decimal | 7.5k | 7.5k |
37 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The zero value is 0, so a zero-valued struct field is a valid number
The first feature on the list is unusual enough to notice: the zero-value is 0, and is safe to use without initialization. Most numeric wrapper types in Go leave you with something unusable until you construct it, which means every struct field and every value coming out of a decoder needs an explicit check. Here a declared but unassigned Decimal is simply zero. The remaining arithmetic follows from the type being fixed-point rather than binary floating point: addition, subtraction and multiplication carry no loss of precision, while division is the exception and is performed at a precision you specify. The serialization features are the ones that decide whether it survives contact with a real application, database/sql, JSON and XML, and MongoDB BSON as Decimal128, because a decimal type that cannot round-trip through your storage layer or your HTTP responses is arithmetic you would end up converting back to a string anyway.
Division is the only operation that asks you how much precision to keep
Three of the four arithmetic operations are exact by construction, and one is not. Division returns a value at a precision you supply, which is an honest design rather than a hidden one, since a repeating decimal has no exact representation and something has to give. By default, Div results are rounded to 16 decimal places through the DivisionPrecision setting, and DivRound is the per-call alternative. The practical consequence for a totals calculation is that you should decide where the rounding happens deliberately. If you round each line item and then sum, the sum can differ from rounding the sum of unrounded lines, and the choice belongs in your code rather than in a library default you did not read.
The 1/3 example is the argument for this over big.Rat
The FAQ does not argue that big.Rat is wrong for rationals, only that Decimal is better for money, and it argues with a worked example. Take two numbers x and y both representing 1/3, and z = 1 - x - y. With rationals, printing has to stop somewhere; say it stops at three decimal digits, and you get 0.333, 0.333 and 0.333, which is where the missing 0.001 went. With Decimal at precision 3, the strings printed represent the numbers exactly: x and y are equal to 0.333, and z = 1 - x - y is .334. No money is unaccounted for. The FAQ is careful to add that you still have to be careful. If you split a total N three ways you cannot send N/3 to three people; you have to pick one person to receive N - (2/3*N), so that person gets the fraction of a penny remainder. The library makes the arithmetic honest, it does not make the business decision for you.
Every method allocates, which is the price of never mutating in place
The FAQ explains why the API does not look like big.Int's, and the explanation is the performance trade-off in reverse. big.Int's API is built to reduce allocations for maximum performance, which makes sense for its use case but leaves an API that is awkward and easy to misuse: you add two big.Ints with `z := new(big.Int).Add(x, y)`, and a developer unfamiliar with it may write `z := a.Add(a, b)`, which modifies a, sets z as an alias for a, and quietly modifies every other alias of a. Decimal avoids that class of bug by refusing to mutate. Decimals behave like other Go number types, where `a = b` will not deep copy b into a, but it is impossible to modify a Decimal because all methods return new Decimals and leave the originals alone. The cost is extra allocations, so Decimal is less performant. The author's assumption is stated plainly: if you are using Decimals you probably care more about correctness than performance. The alternatives list is where you go when that assumption is wrong.
The alternatives list is a menu of precision against speed
The README names five alternatives and describes each by what it trades, which is more useful than a ranking. cockroachdb/apd is arbitrary precision, mutable, with a rich API similar to big.Int and more performant than this library. alpacahq/alpacadecimal is high performance at low precision, 12 digits, with a fully compatible API. govalues/decimal is high performance and zero-allocation at low precision, 19 digits. quagmt/udecimal is high performance and mostly zero-allocation, with up to 19 digits after the decimal point. greatcloak/decimal is a fork focusing on billing and e-commerce web application use cases and includes out-of-the-box BSON marshaling support. Read the two axes together and the choice becomes mechanical. If your values are small and you need throughput, a 12 or 19 digit type is enough. If you need arbitrary precision and can accept a big.Int-style mutable API, apd is the swap. BSON alone is no longer a reason to switch, since this library now lists MongoDB BSON serialization as Decimal128 with the official Go driver v2; the billing fork targets billing and e-commerce use cases.
The stated precision ceiling is 2 to the 31 digits after the point
The note at the top of the README sets one boundary, delivered with a scare-quoted only: the library can only represent numbers with a maximum of 2^31 digits after the decimal point. Read it as what it is, a statement about the fixed-point representation rather than a practical constraint you will hit. Nobody stores two billion fractional digits. What it does tell you is that this is a decimal type, so a number such as 0.1 is held exactly; the same note adds that inexact results like Div and Sqrt are rounded to 16 decimal places by default and decoded input is limited to exponents up to 10,000. That property is the entire reason to reach for this package over float64, and the FAQ states that case directly: float64, or any binary floating point type, cannot represent numbers such as 0.1 exactly, and the example there prints 9.999999999999831 where you would expect 10, with the errors accumulating over time.
The floor is Go 1.10, and the newest tag is from April 2024
Installation is a single module fetch:
go get github.com/shopspring/decimalThe stated requirement is Go version >= 1.10, and go.mod agrees, declaring the module as github.com/shopspring/decimal with `go 1.10`. That floor is unusually old, and the tree shows why the project has not had to move it: the package is a handful of files, decimal.go, const.go, encoding.go and math.go, with tests including decimal_go124_test.go, so newer language features are exercised without raising the module's declared minimum. After a long gap following v1.4.0 on 2024-04-12, releases picked up again with v1.5.0 on 2026-10-05 and v1.6.0 on 2026-10-18, and the last push on master is dated 2026-11-01. Documentation lives on godoc rather than in the repository. On licensing, the repository's own record leaves the licence field unstated, so read the LICENSE file at the repository root.
Editorial conclusion
Use it wherever rounding errors would reach a customer: prices, tax, fees, invoice splits, anything persisted to a column a human reads. Do not use it in a hot numeric loop, because every method allocates, and switch to one of the alternatives the README lists if you need speed at lower precision. Before you adopt it, read the FAQ section on big.Rat rather than assuming Decimal makes money splitting automatic, because splitting a total three ways still needs a decision about who receives the remainder.
Frequently asked questions
What is shopspring/decimal used for?
It is a Go implementation of arbitrary-precision fixed-point decimal numbers, aimed at money and totals. Addition, subtraction and multiplication keep full precision, division is performed at a precision you specify, and the type serialises through database/sql, JSON and XML. The zero value is 0 and is usable without initialisation.
Why not use float64 for money in Go?
Because float64, or any binary floating point type, cannot represent numbers such as 0.1 exactly. The example in the README prints 9.999999999999831 where you would expect 10, and those small errors accumulate over time. Decimal prints strings that represent the stored numbers exactly.
What are the alternatives to shopspring/decimal?
The README lists five: cockroachdb/apd, arbitrary precision with a mutable rich API similar to big.Int and better performance; alpacahq/alpacadecimal, high performance at 12 digits of precision with a fully compatible API; govalues/decimal, high performance and zero-allocation at 19 digits; quagmt/udecimal, high performance and mostly zero-allocation with up to 19 digits after the decimal point; and greatcloak/decimal, a fork aimed at billing and e-commerce use cases that includes out-of-the-box BSON marshaling.
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/shopspring-decimal)Star history chart for your README
[](https://hysenlabs.com/projects/shopspring-decimal)Was this useful?