AmazingPrint: pretty printing Ruby objects, and why it was forked

The fork exists because the original stopped

AmazingPrint is a fork of awesome_print, and the README gives the reason in the first paragraph: awesome_print became stale, and this should be used in its place to avoid conflicts.

That is a small sentence with a large consequence for a dependency. A pretty printer is the kind of library that sits in the Gemfile of a lot of projects, gets used in development and in console sessions, and is never touched again. When its upstream goes quiet, the options are to keep the old version pinned on an old Ruby, to vendor it, or to fork it and take on the maintenance. This is the third of those.

What the library does is narrow and well defined. It pretty prints Ruby objects in full colour, exposing their internal structure with proper indentation, and Rails ActiveRecord objects and usage within Rails templates are supported via included mixins.

The supported versions are Ruby 3.2 and above, and Rails 6.1 and above. Those floors are the clearest evidence of what the fork has bought. A fork that drops support for interpreters nobody runs any more is a fork that can be maintained.

Installing it is a gem install amazing_print, or a git clone of the repository if you want to work from source. The licence is MIT, the primary language is Ruby, the default branch is main, and the releases are 1.8.1 on 2025-05-22, 2.0.0 on 2025-10-08 and 3.0.0 on 2026-09-17, with the last push on the same day as the newest release.

The options are the real interface

Using it takes two lines:

require "amazing_print"
ap object, options = {}

Everything after that is the options hash, and the README lists the defaults in full, which is a better specification than most libraries ship:

indent:        4,            # Number of spaces for indenting.
index:         true,         # Display array indices.
html:          false,        # Use ANSI color codes rather than HTML.
multiline:     true,         # Display in multiple lines.
colors:        :values_only, # Controls what should be colored. Can be one of :all, :values_only, or :none
raw:           false,        # Do not recursively format instance variables.
sort_keys:     false,        # Do not sort hash keys.
sort_vars:     true,         # Sort instance variables.
limit:         false,        # Limit arrays & hashes. Accepts bool or int.
hash_format:   :symbol,      # The format for printing hashes. Can be one of :json, :rocket, or :symbol
class_name:    :class,       # Method called to report the instance class name. (e.g. :to_s)
object_id:     true,         # Show object id.

Several of these deserve a second look. The indent option is documented as a number of spaces, but the examples pass a negative value of -2 to left align hash keys, so the sign carries meaning. The colors option has three settings, and the default of :values_only means the colours are applied to values rather than to the whole structure, which is the difference between output that is readable and output that is a colour chart.

The limit option is the one that changes the shape of the output rather than its decoration, and it accepts either a boolean or an integer. The raw option controls whether instance variables are formatted recursively, and the two sort options decide whether hashes and instance variables come out in a stable order, which is what makes the output diffable between two runs.

Colour is assigned per class, and there are two palettes

The colour configuration is a hash keyed by class name, so the colour of a value is a property of what it is rather than of where it sits:

color: {
  args:       :whiteish,
  array:      :white,
  bigdecimal: :blue,
  class:      :yellow,
  date:       :greenish,
  falseclass: :red,
  integer:    :blue,
  float:      :blue,
  hash:       :whiteish,
  keyword:    :cyan,
  method:     :purpleish,
  nilclass:   :red,
  rational:   :blue,
  string:     :yellowish,
  struct:     :whiteish,
  symbol:     :cyanish,
  time:       :greenish,
  trueclass:  :green,
  variable:   :cyanish
}

The keys are the class names the library knows about, and note that the false and true classes get the same treatment as integers and strings, which is what makes a boolean stand out in a long hash. The values are the sixteen colour names the library supports:

:gray, :red, :green, :yellow, :blue, :purple, :cyan, :white
:grayish, :redish, :greenish, :yellowish, :blueish, :purpleish, :cyanish, :whiteish

The two families are the eight saturated colours and the eight with the ish suffix, which is the library's way of expressing a lighter shade of the same hue, and a colon symbol is the natural way to write that in Ruby. The default map uses a mixture of the two, so a string is yellowish and a symbol is cyanish while an integer is plain blue, which keeps the brightest colours for the things you scan for first.

Since the map is just an option, overriding it is a matter of passing a different colour hash, and the html option switches the output to HTML spans rather than ANSI codes, which is how the library is used from a Rails template.

ap, and the .ai escape hatch for strings

The ap method is the entry point, and the README shows it being used on a plain array, a hash, a class, a list of methods, and a Rails relation. Two of the examples are about the mechanics rather than the data.

The first shows that ap returns its argument, so it can be used inside an expression:

ap 42 == ap(42)

which prints 42 and then true, because the comparison receives the value back. That is a small property with a large effect on how you use the tool in a console, since you can wrap a value in ap wherever you would have written it and keep the expression intact.

The second is the Object#ai method, which returns an ASCII encoded string rather than printing to the terminal:

irb> "awesome print".ai
=> "\e[0;33m\"awesome print\"\e[0m"

The returned value is the coloured text with ANSI escape sequences embedded, and the example shows a string literal in yellow inside the escape codes. That method is what makes the library usable outside a terminal: it is how you would put coloured output into a log line, a test failure message or a JSON payload that something else renders, since the library's html option covers the other direction of the same problem.

So there are two output modes, ANSI for a terminal and HTML for a document, and ai is the one that gives you the raw string to do as you like with.

How the output reads: indices, collapsed ranges and aligned keys

The examples in the README are worth reading as a description of the output format, because the format is what you actually look at all day.

Arrays are printed with their indices, and the index column is padded so that the values line up:

[
    [0] false,
    [1] 42,
    [2] [
        [0] "forty",
        [1] "two"
    ],
    [3] {
           :class => Time < Object,
             :now => Fri Apr 02 19:55:53 -0700 2010,
        :distance => 4.2e+43
    }
]

Nested structures are indented relative to their parent, and hash keys are right-aligned against the longest key in the hash, which is why the class, now and distance lines do not start at the same column. A negative indent flips that alignment so the keys line up on the left, which is what the second example does with :indent => -2, and which is more readable in a narrow terminal.

The limit option is the feature that keeps a large collection from drowning the output. With :limit => true, a thousand-element array is printed as the first few elements, an elided range and the last few:

ap some_array, :limit => true
[
    [  0] 1,
    [  1] 2,
    [  2] 3,
    [  3] .. [996],
    [997] 998,
    [998] 999,
    [999] 1000
]

With :limit => 5, only five elements are shown before the elision. And with :multiline => false, a self-referential array prints on one line with the recursive reference collapsed to [...], which is how a cycle is displayed without hanging the printer.

Rails support is a mixin, and the console output is the best example

Rails ActiveRecord objects and usage within Rails templates are supported via included mixins, and the README's Rails console example shows exactly what you get.

Calling ap on a relation of records prints each record with its instance variables expanded and indented, which is the thing you usually want to see and the thing plain inspect does not give you:

rails> ap Account.limit(2).all
[
    [0] #<Account:0x1033220b8> {
                     :id => 1,
                :user_id => 5,
            :assigned_to => 7,
                   :name => "Hayes-DuBuque",
                 :access => "Public",
                 :website => "http://www.hayesdubuque.com",
         :toll_free_phone => "1-800-932-6571",
                   :phone => "(111)549-5002",
                    :fax => "(349)415-2266",
             :deleted_at => nil,
             :created_at => Sat, 06 Mar 2010 09:46:10 UTC +00:00,
             :updated_at => Sat, 06 Mar 2010 16:33:10 UTC +00:00,
                  :email => "[email protected]",
        :background_info => nil
    },

The second form, ap Account, prints the class itself with the attribute names and their types, which is a quick way to check the shape of a model without opening the schema file.

The mixin arrangement is what makes the template case work. Because the support arrives as included mixins rather than as a special call, a Rails application can require the library once and then use ap anywhere, including inside a view, where the html option takes over and the output is markup rather than escape codes.

The repository shows a maintained gem, not a copied one

The top-level listing is the usual set for a Ruby gem with a real test suite, and it is worth reading as evidence that the fork is maintained rather than merely republished.

There is a spec/ directory and a.rspec file, so the tests are RSpec, and a Rakefile to run them. There is a.rubocop.yml together with a.rubocop_todo.yml, which is the pattern of a project that has adopted a linter and is working through the existing violations rather than turning the linter off, and a.codeclimate directory with a.codeclimate.yml for hosted code quality analysis. A Gemfile, an amazing_print.gemspec and an Appraisals file with a gemfiles/ directory point at multi-gemfile testing, the standard approach for a library that has to work across a range of dependency versions.

There is also a CHANGELOG.md, a CONTRIBUTING.md, an.editorconfig and a.github/ directory, plus the demo animation used in the README.

The version history is where the maintenance shows most clearly. Two major versions in under a year, 2.0.0 in October 2025 and 3.0.0 in September 2026, with the Ruby floor at 3.2 and the Rails floor at 6.1. Major bumps in a library like this are how a maintainer signals breaking changes to a user base that pins versions in a Gemfile and often does not update.

So the practical question for anyone arriving at this choice is not whether the printer is good, since the original's output format is what they would be getting, but which version of it they can live with. The fork answers it by dropping old interpreters, which is what makes the newer Ruby versions work at all.

Editorial conclusion

Adopt AmazingPrint if you are in a Ruby or Rails codebase and want debug output that shows an object's internal structure at a glance, because the fork exists to keep that capability maintained on current Ruby versions and the option set is deep enough for real use. Do not mix it with the original awesome_print gem in one project, because the README says the fork exists to be used in its place to avoid conflicts, and do not expect the print output to be a stable format, since it is meant for reading by a person. Before you upgrade anything, check the major version jumps, 1.8.1, then 2.0.0, then 3.0.0, in the CHANGELOG, and remember the Ruby floor is 3.2 and the Rails floor is 6.1, so the older gem may still be the only option on an old application.

Frequently asked questions

Official sources

1. amazing-print/amazing_print on GitHub
2. Issues
3. License: MIT
4. README
5. Releases