Library / SDK
RubyMoney/money avatar
RubyMoney/money

money: integer cents, three ways to spell a currency, and exchange examples that miss two decimal places

A Ruby Library for dealing with money and currency conversion.

2,882 stars651 forksRubyMIT

At a glance

What is it?
The money gem wraps an amount and its currency in two classes and keeps values as integer cents to avoid float rounding. Reading the file closely turns up an exchange example that is off by a factor of one hundred, a development install that uses a retired protocol, and two major upgrade guides with no releases behind them.
Who is it for?
money is a sound choice for storing amounts as integer cents, and its currency registration API is the part worth copying into your own code. Two things to weigh first.
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 47 days ago.
What is it written in?
Mainly Ruby, 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.

From daily snapshots

Star history

  • RubyMoney/money2,882 ★ · -1
Star history
Repository2026-10-042026-11-15
RubyMoney/money2.9k2.9k

-1 Stars in the last 42 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The exchange example's expected values are a hundred times too small

The Currency Exchange section sets two rates by hand and then converts:

ruby
Money.add_rate("USD", "CAD", 1.24515)
Money.add_rate("CAD", "USD", 0.803115)

Money.us_dollar(100).exchange_to("CAD")  # => Money.from_cents(124, "CAD")
Money.ca_dollar(100).exchange_to("USD")  # => Money.from_cents(80, "USD")

One hundred US dollars at 1.24515 is 124.515 Canadian dollars, which in the integer-cent representation this library uses is 12451 cents, not the 124 in the comment. The reverse example behaves the same way: one hundred Canadian dollars at 0.803115 is 80.3115 dollars, or 8031 cents, not 80. Both comments do line up if the argument is 1 instead of 100, since 1.24515 dollars is 124.515 cents and 0.803115 dollars is 80.3115 cents. So the rate table is fine and the arithmetic is not, which means the rounding rule you would infer from these two lines is one hundred times finer than the one the code produces.

String parsing was pushed out into a separate gem

The line under the badges points at the monetize gem for anyone who misses string parsing, which tells you the split between this library and its companion. A Money object here is built explicitly, from a number of cents and a currency identifier:

ruby
money = Money.from_cents(1000, "USD")
money.cents     #=> 1000
money.currency  #=> Currency.new("USD")

There is no parse method in the visible surface, and no format-string round trip either, so a value that arrives as text from a form or an API response has to be converted before it becomes money rather than after. That is the whole reason the two libraries exist, and it is worth knowing before you pick one: the currency logic lives in money, the string handling lives in monetize, and an application that stores amounts as integer cents but receives them as strings needs both.

No default currency means the error arrives at object construction

A default currency is not set by default, and the consequence is stated rather than demonstrated: if none is set, the library raises when you initialize a Money object without explicitly passing a currency, or when you parse a string that does not contain one. Setting one for an application is a single assignment:

ruby
Money.default_currency = Money::Currency.new("CAD")

The file suggests `config/initializers/money.rb` as a good place for it in a Rails application. Two things are worth noticing about where that failure lands. It is a runtime raise on first use rather than a boot-time check, so a code path that only builds money on a rarely taken branch can sit latent for a long time. And the suggested fix is a global assignment in an initializer, which means the default applies to every Money built anywhere in the process, including code that has no business assuming Canadian dollars.

Three spellings of one currency identifier cross the same API

The file uses three forms for the same object. Constructor calls take strings in upper case, `Money.from_cents(1000, "USD")`. The lookup by ISO 4217 numeric code takes an integer and returns a currency built from a symbol, `Money::Currency.find_by_iso_numeric(978) #=> Money::Currency.new(:eur)`. And the currency table hands back lower-case symbols, since the two helper methods in the priority example end with `major_currencies(Money::Currency.table) # => [:usd, :eur, :gbp, :aud, :cad, :jpy]` and `all_currencies(Money::Currency.table) # => [:aed, :afn, :all, ...]`. So an identifier that comes back from the table is not in the form the constructor examples show. Nothing in the file reconciles the three, and any application that feeds table output back into the constructor has to settle the case question itself.

A constructor named from_cents meets a currency with no subunit

Cents-based storage is the stated reason floating point rounding is avoided, and `currency.cents_based? #=> true` is the flag that reports it. The exponent is where that assumption narrows:

ruby
Money::Currency.new("USD").exponent  # => 2
Money::Currency.new("JPY").exponent  # => 0
Money::Currency.new("MGA").exponent  # => 1

The yen has exponent 0, so it has no fractional unit at all and the smallest amount the representation can hold is one yen. With a method called from_cents, an integer argument means something different depending on the currency you pass alongside it: 1000 with USD is ten dollars, and 1000 with JPY is one thousand yen. The same applies to the registered-currency hash, where `subunit_to_unit: 100` for the dollar states the proportion directly, so a custom currency with a different proportion changes what the argument counts without changing the method name.

The development install path uses the retired git protocol

Stable releases install the way most gems do:

bash
gem install money

The development version is given as three lines, and the first uses the `git://` protocol:

shell
git clone git://github.com/RubyMoney/money.git
cd money
bin/rake install

That protocol is the unauthenticated one, and it is not what the rest of the file points at, since every other link in the badges and the Resources section uses https. The last line is also unusual: the rake task is invoked through a path inside `bin/` rather than through bundler, even though the tree carries a `Gemfile`, a `Rakefile`, and a `money.gemspec`. So the one instruction meant for people hacking on the library itself is the one written against an older transport and a bare task runner, while the stable path is the one that will work.

Two major upgrade guides with no releases to line up against

The warning at the top of the file asks you to read the upgrade guides before moving to a new major version, and the tree holds `UPGRADING-6.0.md` and `UPGRADING-7.0.md` for exactly that. The repository itself has no GitHub releases, so there is no tag list, no changelog view, and no release note to compare those guides against, even though a `CHANGELOG.md` sits in the same tree. The last push is dated 2026-09-23, which tells you the code moved recently and not which version of it you would get. The resources section also links the website over https while the recorded homepage for the repository is the plain http form of the same address, and the tree pairs `.rubocop.yml` with `.rubocop_todo.yml`, the file where style offenses are recorded as accepted rather than fixed.

The usage examples stop partway through two expressions

Two code blocks end before the expression finishes. The Arithmetic example has four labelled groups, and the last line of the fourth is:

ruby
Money.from_cents(1000, "USD") + Money.f

so the addition it sets up never reaches a second operand, a result, or a comment showing the return value, while the three groups before it, Comparisons, Arithmetic, and the currency inspection above them, each end with a value. The comparison block further down stops mid-token as well, at `Money.from_cents(1000, "EU`, on the line after the spaceship example whose comment reads `# => 1; 9.00 USD is smaller`. Neither gap is filled elsewhere in the file, so the two behaviours an application depends on most, adding two amounts and comparing across currencies, are the two the visible documentation does not finish showing.

Editorial conclusion

money is a sound choice for storing amounts as integer cents, and its currency registration API is the part worth copying into your own code. Two things to weigh first. There is no default currency, so an unconfigured application raises at the moment it builds a Money object rather than at boot, and the file says to set it in a Rails initializer. And the exchange examples you would use as a template are arithmetically wrong by a factor of one hundred, so verify the rounding behaviour of exchange_to against your own rates before you trust it with real amounts. Install from RubyGems; treat the git:// development path as documentation of history rather than a working instruction.

Frequently asked questions

How does the money gem store monetary values?

As integers in cents, which is the stated reason floating point rounding errors are avoided. A Money object pairs that integer with a Money::Currency instance, and currency.cents_based? returns true for currencies defined that way.

How do you exchange money with the money gem?

Through an exchange bank object, and the default one needs rates supplied by hand using Money.add_rate. The file shows Money.add_rate("USD", "CAD", 1.24515) followed by Money.us_dollar(100).exchange_to("CAD"), with expected results given in the comments.

Does money set a default currency?

No, and the file says so directly. Without one, initializing a Money object without a currency raises an error, and the suggested fix is Money.default_currency = Money::Currency.new("CAD"), placed in config/initializers/money.rb for Rails.

Can money parse a string like "$10.00"?

Not in this library. The file points at the separate monetize gem for anyone who misses string parsing, and the construction shown here is explicit, using Money.from_cents(1000, "USD") rather than parsing text.

How do I add my own currency to money?

With Money::Currency.register and a hash of attributes, including priority, iso_code, iso_numeric, name, symbol, subunit, subunit_to_unit, decimal_mark, and thousands_separator. All attributes except iso_code are optional, and symbol has to be UTF-8 encoded.

What are the requirements for using the money gem?

Your app must use UTF-8, since there are non-ASCII currency attributes. Stable releases install with gem install money, and the development version is documented as a git clone followed by bin/rake install.

Official sources

  1. Issues
  2. License: MIT
  3. Project website
  4. README
  5. RubyMoney/money on GitHub
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.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/rubymoney-money.svg)](https://hysenlabs.com/projects/rubymoney-money)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/rubymoney-money.svg)](https://hysenlabs.com/projects/rubymoney-money)

Was this useful?