Installation

Install Nanoc using RubyGems:

% gem install nanoc

For detailed installation instructions, read on.

Ruby 3.x

On Ruby 3.0 and later, you might get this error error when running nanoc view:

LoadError: Couldn't find handler for: puma, thin, falcon, webrick.

This happens because Ruby 3.0 and later does not come with WEBrick by default, while older Ruby versions (2.x) do.

To resolve this, add WEBrick to your Gemfile. You can do so by running the bundle add webrick command. If you happen to not use Bundler and thus have no Gemfile, you can install WEBrick using gem install webrick.

Compatibility guarantees

Nanoc guarantees backwards compatibility within the same major version, starting from Nanoc 3.0 (released in 2009). This means that it is possible to upgrade from any 4.x to any newer 4.x version without extra work.

We recommend specifying the version of Nanoc using the ~> operator in the Gemfile, and specifying only the major and minor version. For example:

gem 'nanoc', '~> 4.13'

This version constraint tells Bundler to use at least Nanoc version 4.13, but never upgrade beyond version 4. This way, running bundle update nanoc will upgrade Nanoc to the last compatible version.

We recommend updating Nanoc regularly. New versions not only come with new features, but also with bug fixes and performance improvements that continuously make Nanoc more enjoyable to use.

Supported platforms

Language version: Ruby 2.5 or higher. Nanoc might run fine on older versions, but there are no guarantees that it will.

Implementation: CRuby. Alternative Ruby interpreters, such as JRuby and Rubinius, might be able to run Nanoc, but there are no guarantees that they will be able to do so properly.

Operating system: macOS, Linux. Nanoc runs mostly fine on Windows, with some limitations. Windows is not officially supported at this point, but that is being worked on.

Installing Ruby

Nanoc requires Ruby to run. Nanoc supports the official Ruby interpreter from version 2.5 up.

Ruby may already be installed on your system. To check, open a terminal window and type ruby --version. If you get “command not found”, Ruby is not yet installed. Otherwise, you will see which version of Ruby you have:

% ruby --version
ruby 3.3.6 (2024-11-05 revision 75015d4c1f) [x86_64-linux]
%

To install Ruby, follow the installation instructions on the Ruby website.

Installing Nanoc

All dependencies are now taken care of, and you can now install Nanoc itself:

% gem install nanoc

To make sure that Nanoc was installed correctly, run nanoc --version. It should print the version number along with some other information, like this:

% nanoc --version
Nanoc 4.13.3 © 2007–… Denis Defreyne.
Running ruby 3.3.6 (2024-11-05) on x86_64-linux with RubyGems 3.5.22.
%

If you get a “command not found” error when trying to run nanoc, you might have to adjust your $PATH to include the path to the directory where RubyGems installs executables.

The current version of Nanoc is 4.13.3, released on November 23rd, 2024. You can find the release notes for this version as well as release notes for older versions on the Release notes page.

If you’re on Windows and are using the Windows console, it’s probably a good idea to install the win32console gem using gem install win32console to allow Nanoc to use pretty colors when writing stuff to the terminal.