How to install Qgoda and its dependencies on your local system

You can install and run Qgoda in a couple of ways.

macOS (Homebrew)


Install Homebrew and tap the gflohr-homebrew formula repository before you install the formular qgoda:

$ brew tap gflohr/homebrew
$ brew install qgoda


You can update with:

$ brew update
$ brew upgrade qgoda

Uninstall Qgoda

$ brew uninstall qgoda
$ brew untap gflohr/homebrew

All Other Platforms

Please check the section Pre-Requisites below for additional software necessary to run Qgoda on your system.

Installing from CPAN

The Qgoda version on CPAN is currently outdated and should not be used!

If you are happy with version 0.9.8, then you can:

$ cpanm Qgoda

Installing From Git

Clone the Qgoda git repository and follow the usual way of installing Perl modules:

$ git clone
$ cd qgoda
$ cpanm .


Installing Node.js

Node.js is an interpreter for JavaScript that runs outside of the browser. It is not a strict requirement for Qgoda but most Qgoda sites will make use of it.

The Node.js website usually offers a download link for the software but if you are using a package manager, you should rather install Node.js with that.

Yarn or NPM

NPM is the Node Package Manager and is used to install packages and their dependencies for Node.js. Yarn is an alternative to NPM and does essentially the same.

The official Qgoda themes all use Yarn but you can easily change that. First, exchange yarn with npm in the section scripts of the theme's package.json and then do the same for the configuration variable helpers in Qgoda's main configuration file _qgoda.yaml.

Installing NPM

As npm ships with Node.js you normally don't have to install it. If you have installed Node.js with your package manager, it is possible that you explicitely have to install npm. An example for such a package manager is MacPorts.

Installing yarn

See for instructions.

Using Docker

An easy method of installing Qgoda is to use Docker:

  1. Install Docker. On Linux/Unix systems, Docker will be available from your package manager. On Mac OS X you can install Docker with Mac Ports or Homebrew, or - like on Windows - get a pre-compiled binary from

  2. Start Docker. You may want to start the docker daemon automatically. Check your vendor's documentation for that!

  3. In a shell, run the command $ docker run --name qgoda -p 3000:3000 --rm -it -v $(pwd):/data gflohr/qgoda watch. You may have to add the user that runs the command to the group docker if you get an error like permission denied.

  4. You can create an alias, so that you do not have to type in the Docker command-line options all the time. Depending on your operating system, you have to open ~/.bash_profile, ~/.bashrc, ~/.alias, ~/.zshrc or similar and add this line:

alias qgoda='docker run --name qgoda -p 3000:3000 --rm -it -v $(pwd):/data gflohr/qgoda'

With this alias, you can now run all qgoda commands like the native version described in this documentation.

This website uses cookies and similar technologies to provide certain features, enhance the user experience and deliver content that is relevant to your interests. Depending on their purpose, analysis and marketing cookies may be used in addition to technically necessary cookies. By clicking on "Agree and continue", you declare your consent to the use of the aforementioned cookies. Here you can make detailed settings or revoke your consent (in part if necessary) with effect for the future. For further information, please refer to our Privacy Policy.