Installation

Install Nanoc using RubyGems:

% gem install nanoc

For detailed installation instructions, read on.

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.11'

This version constraint tells Bundler to use at least Nanoc version 4.11, 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.4 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.4 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 2.6.3p62 (2019-04-16 revision 67580) [x86_64-linux]
%

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

Installing Nanoc

All dependencies are now taken care of, and installing Nanoc should now be easy:

% 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.11.16 © 2007–2019 Denis Defreyne.
Running ruby 2.6.3 (2019-04-16) on x86_64-linux with RubyGems 3.0.3.
%

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.11.16, released on April 26th, 2020. 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.

Installing from git

You can also install Nanoc from the repository if you want to take advantage of the latest features and improvements in Nanoc. Be warned that the versions from the repository may be unstable, so it is recommended to install Nanoc from RubyGems if you want to stay safe. You can install Nanoc from the git repository like this:

~% git clone git://github.com/nanoc/nanoc.git
~% cd nanoc
~/nanoc% gem build nanoc.gemspec
~/nanoc% gem install nanoc-*.gem