Getting Started | Nikola

Setting up a Nikola site is really easy. You will need a few minutes’ time and a Python 3 interpreter.
Nikola is free open-source software, under the MIT license.
The best way to install Nikola is to use pip in a virtual environment. We recommend installing the "Nikola[extras]" distribution to access all built-in Nikola features. Follow instructions on the right/below.
If you’ve never worked with Python virtual environments, you might want to read Python Virtual Environments in Five Minutes.
Installing "Nikola[extras]" as explained above installs software that Nikola might use. This is quite a lot of software. Alternatively, you can drop the [extras] specifier and install such software later, as you find out you want it. Nikola makes this reasonably convenient, as explained below.
We don’t recommend using Pipenv, Poetry, or PDM to manage Nikola. Those package managers are aimed at people developing software using Python, not running software written in Python, so using them will not offer a good user experience.
Nikola supports Windows! Here are a few things to keep in mind:
Installing Nikola on macOS is easy. You can use Homebrew, MacPorts, Fink, or the Apple-provided Python 3 interpreter.
We recommend using Homebrew. After you install it, you can run brew install python3 to install Python 3. You can then follow the instructions on the right/below. Your venvs may require fixing, reconfiguration or recreating if you update Python.
Other package/port managers, such as MacPorts or Fink may be used if you prefer them and have those installed. Make sure to use only one manager to avoid conflicts.
The Apple-provided Python 3 will work too. Starting with Catalina, Python 3 is available, and it seems to be updated reasonably often. You might need to install Xcode Command Line Tools (xcode-select --install), or possibly the full Xcode environment (from the App Store), to use it.
Nikola is packaged for some Linux distributions, you may get that instead of installing via pip (which is the recommended way). Keep in mind that those packages might be outdated and that we don’t support versions that are too old. Proceed with care!
You can also install Nikola from GitHub. This will get you the code that is still under development. It probably has bugs, but there are often new features or bugfixes. Start by creating and activating a virtual environment.
For development work, or if you otherwise want a local clone of the repository, use this:
You should not need to compile any C extension modules to run Nikola. Both lxml and Pillow have pre-compiled wheels available for Windows, macOS and Linux (compatible with all distributions).
However, if pip still attempts to compile those packages, you may need to do the following:
There are unofficial Docker images by Olaf Meeuwissen (based on Alpine Linux) available:
Check out the image’s README for details and usage hints.
There is also a Dockerfile by Rob Brewer, based on Arch Linux and official Arch packages.
There are also Snapcraft packages (snap install nikola --edge), but those inherit many limitations of the platform and are not recommended for daily use.
The easy way to install Nikola is to include, in the installation, a lot of additional software that you may or may not need. This is what happens when installing Nikola[extras] as mentioned above, and is recommended for casual and first-time users.
Maybe you have reason to be careful about which packages you download and install. If so, you can choose to install plain Nikola without [extras]. This will get you going. When, later, you ask Nikola to provide functionality that needs a dependency (i.e., additional software on which that Nikola functionality depends), and that dependency has not yet been installed, you will receive a helpful error message telling you what is missing. E.g., when using nikola auto --browser for the first time, you might see error message text telling you aiohttp and watchdog are needed to proceed:
In this situation, run pip install aiohttp watchdog and then repeat your original nikola auto --browser.
After installing Nikola, you should create a site. A site is a collection of all assets needed to create your site: configuration, posts, pages, images, and all other files and customizations. This is the important data, so put it where you put that kind of things.
To create a site, you need to run nikola init --demo <directory_name>. A friendly wizard will be launched, letting you configure your site easily. The --demo option is used to fill your site with some demo content. (If you do not want the wizard, use the --quiet argument.)
If you’re using a virtual environment, you should use the path to the Nikola script in your virtual environment (bin/nikola init on *nix, Scripts\nikola init on Windows), or alternatively, you can activate the environment (source bin/activate on *nix, Scripts\activate on Windows) and use the nikola command directly.
Do not store your site inside your virtual environment. Virtual environments are meant to be ephemeral (you should be able to delete and recreate one at any time).
You can now build the site you created. Just run nikola build inside your site directory. The output directory will then be filled with the contents of your site, which is now ready to deploy.
Your site currently contains demo content — that is, some Nikola documentation, a demo gallery and listing, and a blog post welcoming you.
You should make it more interesting and personal. Write your own post!
To do that, you can just use nikola new_post -e. (The -e option will open the post in your text editor of choice; many more options are available)
The command will create the file for you in the right place, with the metadata headers and a writing prompt.
By default, Nikola creates posts in reStructuredText. You can read the reStructuredText Primer to get accustomed to the syntax.
If you prefer Markdown, it is also available and configured by default: run nikola new_post -e -f markdo