Skip to content
Terminal output paging - cross-platform, major ruby interpreters
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Add markdown paging example Dec 1, 2018
.gitignore Initial release. May 29, 2015
.rspec Initial release. May 29, 2015
.rubocop.yml Add style rules Mar 16, 2019
Gemfile Update dev dependencies Aug 25, 2018
LICENSE.txt Initial release. May 29, 2015
appveyor.yml Change to restrict bundler and use latest ruby Mar 16, 2019

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.

You can’t perform that action at this time.