Can't install Jekyll Big Sur, endless problems

I see other posts about trouble installing Jekyll on MacOS. I’m really hoping someone will say that there’s a simple package installer that will just run without dependences, but I suspect that’s not the case. I’ve spent about an hour and a half futzing around going from one failure to another and it’s just too frustrating. Maybe there’s a tutorial somewhere that is more robust? Anyway, if you want to be amused by my futzing around and inability to fix the new failure that pops up at every step, see my notes. Suggestions welcome, especially for a better way to do this…

I hear you! Unfortunately, setting up Jekyll means setting up Ruby and a pile of other things. Of course, this is not unique to Jekyll as there are lots of ‘stacks’ that require the stack to be perfectly stacked first :slight_smile:

I am working on a training series that shows how to create a Jekyll website from scratch. I created a full video series that shows you one thing, which is how to install and configure Jekyll, from Ruby on to creating a test website.

This series is unlisted on YouTube, but you can feel free to access it here:

If you click on the YouTube link that appears on the video above, you will be brought into the playlist and you will see all the videos so you can select them and jump around, but I recommend you watch all of them from beginning to end. They are no more than 6 minutes each.

Hope this helps.

Your videos look great, but I’ve already installed Ruby, Homebrew, command line XCode tools, etc, and it looks as if what you do is go through the MacOS instructions for installing Jekyll from the Jekyll home page – but those are exactly the instructions that I followed and that failed (see my linked doc).

A common thing I see is that people end up with Ruby in 2 different places and the install seems to bounce between them.

Look at your full logs and scan thru the messages and see if you see ruby being referenced in 2 different paths. Sometimes it is a little tricky to see.

If you post the full output I can check it - but you need the full output from the terminal, not just the last few lines.

Solution if that is the case is to uninstall ruby and re-install it. I think when people follow the instructions and install ruby they may already have it? not a Mac user so not always sure what is going on with them.

1 Like

OK, reinstalled Ruby. Now I get this error:

% bundle install
Fetching gem metadata from
Fetching gem metadata from
ruby_dep-1.5.0 requires ruby version >= 2.2.5, ~> 2.2, which is incompatible
with the current version, ruby 3.0.1p64

I see another thread about this problem which suggests editing versions in the gemfile, but I don’t see any corresponding lines in that file. (This is for GitHub Pages.)

From your notes, it looks like you are jumping around quite a bit between trying to get a site running locally and not having the base stack set up properly.

Please go through the Jekyll step-by-step documentation, or go through my videos, which are more complete and less prone to error. I did the videos because I regularly missed a step or found a quirk in the documentation, so my videos share experience, not just a 100% walkthrough of the Jekyll documentation. Apple does install Ruby (v2.6.x as of this writing), but my experience is you should install Ruby 3.0.x, and my videos walk you through this. Some of the Jekyll site documentation is incorrect, but I did send the team an issue on GitHub, so my videos are more up to date as of this writing.

Looking at your notes, I decided to figure out what the issues are for the particular site you are having an issue with. If the steps below do not work for you, then again, I think you need to look at making sure you follow every step in the Jekyll install docs or my videos.

If you are properly set up, these steps should do the trick:

  1. Download the .zip of the site you are trying to run from GitHub - AlloyTools/ Website for Alloytools and unzip to a folder on the desktop
  2. Run terminal and cd to that folder
  3. Type bundle update. The bundler runs successfully. I see it uses some older or deprecated dependencies, but the bundler does run without errors. There is a post-install message from html-pipeline that explains some next steps:

Post-install message from html-pipeline:
Thank you for installing html-pipeline!
You must bundle Filter gem dependencies.
See html-pipeline for more details.

  1. Looking at the dependencies link, it looks like it needs Rouge installed, so I type: gem install 'rouge'
  2. For good measure, I type bundle update again, and there are no errors
  3. This step may or may not work (skip to step 8 if you do not encounter any issues): Checking to see if the site will build and run, I type bundle exec jekyll serve; however, it does not run on my brand new virtual machine. Looking at the issue, it is because webrick is not installed. You can see some excellent documentation from @MichaelCurrin at this link: Upgrade to Ruby 3 - update projects 🔩 - DEV Community. I even cover that in my video series. To fix the problem, I type: bundle add webrick
  4. For the second time, run bundle exec jekyll serve
  5. Jekyll builds the site, and I am provided the following URL:
  6. Open a browser and go to the URL, and the site appears to be working:

One of the great things about modern web development is everything comes in packages. You have packages that can detect code and format it for you, packages that can take markdown and convert it to HTML, and so much more. One of the downsides is dependencies are a real pain in the neck, and it takes time and experience to understand how all these pieces and parts work together.

I know how frustrating it must have been when writing the post here, but in the future, try posting one thing at a time, and we can usually help get things working. The notes you shared were frustrating and difficult to decipher since you were not following all the installation steps before trying to get the website running. Next time, if you encounter an issue, please share the specific issue in the subject line, along with details to reproduce the issue, and we can usually all work through it together. Many people here volunteer their time and experience, and in my experience, most people get a response the same day.

I hope you are successful in getting the site running after this detailed walkthrough.

1 Like

Bill – wow, that’s more than I expected. Thank you so much. I’ll do all that as soon as get a chance and hopefully I can get it to work. I do want to say that I very much appreciate the effort that volunteers like you put in. I also recognize the benefits of a package system and dependency manager. But in my experience, if you don’t actually understand the system well – which you generally don’t when you’re installing it for the first time – you’re not in much of a position to deal with small failures as they occur. And even if you follow instructions meticulously, as I thought I did, the package manager can fail because of assumptions that have been invalidated in your particular setup. Maybe someone needs to invent a package manager that runs in the cloud, takes a spec of what modules you want, and generates an executable for you…

@Daniel totally understand. I hope this works! Feel free to respond on this thread if anything I shared does not work and I’m sure we can get through it

I don’t have a google account so I cannot read your notes. Let me know if you post them on the internet too one day :slight_smile: I am on bigsur too and would like to read how you fared

HI, Bill Raymond thank you for your videos , I’ve followed all the steps to install Jekyll on MacBook M1 apple silicon MacOS Montery v 12.01 but I’ve this error message when I want to install ruby@3.0. Please help Thanks :grinning:

mac@MacBook-Pro ~ % ruby-v

zsh: command not found: ruby-v

mac@MacBook-Pro ~ % ruby -v

ruby 2.6.8p205 (2021-07-07 revision 67951) [universal.arm64e-darwin21]

mac@MacBook-Pro ~ % brew install ruby@3.0

fatal: Could not resolve HEAD to a revision

Running brew update --preinstall

==> Auto-updated Homebrew!

Updated 1 tap (homebrew/cask).

No changes to formulae.

Warning: No available formula with the name “ruby@3.0”.

==> Searching for similarly named formulae…

Error: No similarly named formulae found.

==> Searching for a previously deleted formula (in the last month)…

Error: No previously deleted formula found.

==> Searching taps on GitHub…

Error: No formulae found in taps.

mac@MacBook-Pro ~ %

Hi. I missed this question over the break, so I’m sorry for the delay. I never encountered this. Are you logged in as an administrator of the machine? If not, try that if you can.

Maybe just do a brew install ruby and see if that solves the problem.