tty logo

TTY::Pager Gitter

Gem Version Build Status Build status Maintainability Coverage Status Inline docs

Terminal output paging in a cross-platform way supporting all major ruby interpreters.

TTY::Pager provides independent terminal output paging component for TTY toolkit.


Add this line to your application's Gemfile:

gem 'tty-pager'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tty-pager


The TTY::Pager on initialization will choose the best available pager out of SystemPager, BasicPager or NullPager. If paging is disabled then a NullPager is used, which either returns text as is or simply prints it out to stdout on tty devices. Otherwise a check is performed to find paging command to page text with SystemPager. However, if no paging command is found, a BasicPager is used which is a pure Ruby implementation that is guaranteed to work with any ruby interpreter and any platform.

1. Usage

In order to let TTY::Pager pick the best paging mechanism automatically do:

pager =

Then to perform actual content pagination invoke page method with the content to paginate as the argument:"Very long text...")

If you want to use specific pager you can do so by invoking it directly:

pager =

2. Interface


If you want to disable the pager pass the :enabled option set to false:

pager = false)


The BasicPager allows to wrap content at given width:

pager = 80)
pager = 80)


For the BasicPager you can pass a :prompt option to change the page break text:

prompt = -> (page_num) { output.puts "Page -#{page_num}- Press enter to continue" }
pager = prompt)


You can force SystemPager to always use a specific paging tool(s) by passing the :command option: 'less -R') 'less -R')

You also specify an array of pagers to use:

pager = ['less -r', 'more -r'])


By default the SystemPager will check the PAGER environment variable, if not set it will try one of the less, more, cat, pager. Therefore, if you wish to set your preferred pager you can either set up your shell like so:

export PAGER

or set PAGER in Ruby script:



Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request


Copyright (c) 2015 Piotr Murach. See LICENSE for further details.