| title |
|---|
Troubleshooting |
If you ever run into problems installing or using Jekyll, here are a few tips that might be of help. If the problem you’re experiencing isn’t covered below, please check out our other help resources as well.
If you encounter errors during gem installation, you may need to install the header files for compiling extension modules for Ruby 2.0.0. This can be done on Ubuntu or Debian by running:
{% highlight bash %} sudo apt-get install ruby2.0.0-dev {% endhighlight %}
On Red Hat, CentOS, and Fedora systems you can do this by running:
{% highlight bash %} sudo yum install ruby-devel {% endhighlight %}
On NearlyFreeSpeech you need to run the following commands before installing Jekyll:
{% highlight bash %} export GEM_HOME=/home/private/gems export GEM_PATH=/home/private/gems:/usr/local/lib/ruby/gems/1.8/ export PATH=$PATH:/home/private/gems/bin export RB_USER_INSTALL='true' {% endhighlight %}
To install RubyGems on Gentoo:
{% highlight bash %} sudo emerge -av dev-ruby/rubygems {% endhighlight %}
On Windows, you may need to install RubyInstaller DevKit.
On Mac OS X, you may need to update RubyGems (using sudo only if necessary):
{% highlight bash %} sudo gem update --system {% endhighlight %}
If you still have issues, you can download and install new Command Line
Tools (such as gcc) using the command
{% highlight bash %} xcode-select --install {% endhighlight %}
which may allow you to install native gems using this command (again using
sudo only if necessary):
{% highlight bash %} sudo gem install jekyll {% endhighlight %}
Note that upgrading Mac OS X does not automatically upgrade Xcode itself (that can be done separately via the App Store), and having an out-of-date Xcode.app can interfere with the command line tools downloaded above. If you run into this issue, upgrade Xcode and install the upgraded Command Line Tools.
With the introduction of System Integrity Protection, several directories
that were previously writable are now considered system locations and are no
longer available. Given these changes, there are a couple of simple ways to get
up and running. One option is to change the location where the gem will be
installed (again using sudo only if necessary):
{% highlight bash %} sudo gem install -n /usr/local/bin jekyll {% endhighlight %}
Alternatively, Homebrew can be installed and used to set up Ruby. This can be done as follows:
{% highlight bash %} ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" {% endhighlight %}
Once Homebrew is installed, the second step is easy:
{% highlight bash %} brew install ruby {% endhighlight %}
Advanced users (with more complex needs) may find it helpful to choose one of a number of Ruby version managers (RVM, rbenv, chruby, etc.) in which to install Jekyll.
If you elect to use one of the above methods to install Ruby, it might be
necessary to modify your $PATH variable using the following command:
{% highlight bash %} export PATH=/usr/local/bin:$PATH {% endhighlight %}
GUI apps can modify the $PATH as follows:
{% highlight bash %} launchctl setenv PATH "/usr/local/bin:$PATH" {% endhighlight %}
Either of these approaches are useful because /usr/local is considered a
"safe" location on systems which have SIP enabled, they avoid potential
conflicts with the version of Ruby included by Apple, and it keeps Jekyll and
its dependencies in a sandboxed environment. This also has the added
benefit of not requiring sudo when you want to add or remove a gem.
This error can occur during the installation of jekyll-coffeescript when
you don't have a proper JavaScript runtime. To solve this, either install
execjs and therubyracer gems, or install nodejs. Check out
issue #2327 for more info.
On Debian or Ubuntu, you may need to add /var/lib/gems/1.8/bin/ to your path
in order to have the jekyll executable be available in your Terminal.