Setting up a Nikola site is really easy. You will need a few minutes’ time and a Python (3.3+; 2.7 partially supported) interpreter.
Step 1. Install Nikola
There are multiple ways to install Nikola.
- The best way to do it is to use
pipin a virtualenv. We recommend installing the
"Nikola[extras]"distribution to access some extra features, but you can drop the
[extras]specifier if you don’t want them. Note that you might need to install some extra dependencies for lxml and Pillow in order to compile them or to get full functionality.
- You can also download the tarball and install manually.
- Some Linux distributions also have Nikola packaged in its repositories — but please make sure it’s a fresh version.
- If you prefer, a Docker image is also available.
Nikola is free open-source software, under the MIT license.
Nikola supports Windows! Keep in mind, though, that there are some caveats:
- You need to install Python first. You also need to install virtualenv if you want to use it:
py -m pip install virtualenv
Pillowrequire compiled extensions. Compiling them on Windows is hard for most people. Fortunately, compiled packages exist. Check their PyPI pages to find official packages, use the unofficial wheels by Christoph Gohlke, or get them somewhere else.
- Windows has some differences over POSIX, which may cause some features to work incorrectly under Windows. If any problems occur, please do not hesitate to report them. Some of the differences that can cause problems include:
\as path separator (instead of
- the concept of HDD partitions and letters (instead of seamless mounting under one root)
- some characters in paths are disallowed
- CR+LF (aka
\r\n) as the line separator (instead of LF
- Most of our developers don’t run Windows on a daily basis and may not have the full knowledge required to resolve issues relating to Windows.
Installing Nikola on macOS is easy. You can use Homebrew, MacPorts, Fink, or perform a standalone installation using the system Python. For future proof installations that do support all features using Python 3.3+ over macOS system Python is recommended.
With Homebrew (recommended)
- Install Homebrew.
- Install Python (and pip) with
brew install python3
- Install virtualenv with
sudo pip3 install virtualenv
- Follow the instructions /below. The command is
virtualenv. Your virtualenvs may need to be recreated if you update Python.
Nikola is packaged for some Linux distributions, you may get that instead of installing via
pip. Keep in mind that those packages might be outdated and that we don’t support versions that are too old. Proceed with care!
- Arch Linux (AUR): python-nikola for the latest stable release or python-nikola-git for the GitHub master. (official Nikola-supported packages)
- Fedora: python-nikola (incl. python3-nikola)
- Gentoo: www-apps/nikola
- The Debian/Ubuntu package is broken and outdated. The Nikola developers strongly discourage using it and do not support this method of install until this issue is resolved — please install via pip instead.
If you get an error to the effect of
Python.h not found, you need to install development packages for Python.
# sudo apt-get install python3-dev
# sudo dnf install python3-devel
Red Hat/CentOS/Fedora 21:
# sudo yum install python3-devel
Note that many other distros/operating systems (including Arch Linux, *BSD and OS X) do not require such packages, as C headers are included with the base distribution of Python.
If you get errors about various files missing while compiling
Pillow, you must install headers for the
zlib libraries. If you have issues installing Pillow, you might need libraries for certain image formats. Try those commands:
# sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev
# sudo apt-get build-dep python3-lxml python3-pil
# sudo dnf install libxml2-devel libxslt-devel zlib-devel
# sudo dnf builddep python3-lxml python3-pillow
Red Hat/CentOS/Fedora 21:
# sudo yum install libxml2-devel libxslt-devel zlib-devel
# sudo yum builddep python3-lxml python3-pillow
If gcc/cc1 is killed when compiling lxml, you might not have enough RAM — lxml requires at least ~1.5 GB of RAM to compile. To fix this, you can:
- Install a system package and create your virtualenv with the
- Install a system package and symlink it from /usr/lib/pythonX.Y/site-packages to your virtualenv
- Use a temporary swapfile to compile lxml
- Create a wheel on a system with more RAM with
STATIC_DEPS=true pip wheel lxml(must have the same architecture) and install that instead
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.
$ pip install "git+https://github.com/getnikola/nikola#egg=Nikola[extras]"
You can also use tarballs downloaded from GitHub, or
pip install -e with a local clone.
$ virtualenv3 nikola Note: The command might be different in some environments. You might need to use one of the following instead: virtualenv virtualenv-3.x (where x is your Python version) virtualenv -p /usr/bin/python3 Using base prefix '/usr' New python executable in nikola/bin/python3 Also creating executable in nikola/bin/python Installing setuptools, pip, wheel...done. $ cd nikola $ source bin/activate $ pip install --upgrade "Nikola[extras]" ...snip... Successfully installed Nikola
Step 2. Initialize a site
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.
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
$ nikola init --demo my_first_site Creating Nikola Site ==================== This is Nikola. We will now ask you a few easy questions about your new site. If you do not want to answer and want to go with the defaults instead, simply restart with the `-q` parameter. --- Questions about the site --- Site title [My Nikola Site]: My First Nikola Site ...a couple more questions... That's it, Nikola is now configured. Make sure to edit conf.py to your liking. If you are looking for themes and addons, check out https://themes.getnikola.com/ and https://plugins.getnikola.com/. Have fun! INFO: init: A new site with example data has been created at my_first_site. INFO: init: See README.txt in that folder for more information.
Step 3. Build your site
You can now build the site you created. Just run
nikola build. The output directory will then be filled with the contents of your site, which is now ready to deploy.
$ cd my_first_site $ nikola build Scanning posts....done! . render_galleries:output/galleries . render_galleries:output/galleries/demo . render_galleries:output/galleries/index.html . render_galleries:output/galleries/rss.xml . render_galleries:output/galleries/demo/tesla4_lg.thumbnail.jpg ...and many more files in between... . render_tags:output/categories/cat_nikola.xml . render_pages:output/stories/social_buttons/index.html . render_pages:output/stories/quickref/index.html . render_tags:output/categories/python.xml . generate_rss:output/rss.xml . render_pages:output/stories/a-study-in-scarlet/index.html . sitemap:output/sitemap.xml . sitemap:output/sitemapindex.xml . robots_file:output/robots.txt
Step 4. Write your first post
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. You can also use many other input formats; to do this, your site needs some special configuration.
What if I don’t want a blog?
If you want a static site that does not have any blog-related elements, see our Creating a Site (Not a Blog) with Nikola guide.
$ nikola new_post -e Creating New Post ----------------- Title: My First Blog Post! Scanning posts....done! INFO: new_post: Your post's text is at: posts/my-first-blog-post.rst
Step 5. Rebuild your site
When you’re done writing your post, you must rebuild your site to make it visible on your site. Run
nikola build again.
Note that the list of files is much shorter now: Nikola does fast, incremental rebuilds (courtesy of doit). Nikola built only the pages for this post, the indexes, the feeds, and the previous post (to add a Next post navigation button). All the demo pages and assets were left untouched, saving you time and resources (it does not have to work on building some larger things, and
rsync will not have to upload everything)
$ nikola build Scanning posts....done! . render_posts:timeline_changes . render_posts:cache/posts/my-first-blog-post.html . render_sources:output/posts/my-first-blog-post/index.rst . render_archive:output/2015/index.html . render_archive:output/archive.html . render_indexes:output/index.html . render_pages:output/posts/welcome-to-nikola/index.html . generate_rss:output/rss.xml . render_pages:output/posts/my-first-blog-post/index.html . sitemap:output/sitemap.xml . sitemap:output/sitemapindex.xml
Step 6. Start the development server
You’re done! You just created a Nikola site, wrote your first post and built your site. Congratulations!
nikola serve --browser to start the development server and open your site in a web browser. Press Ctrl+C to stop the server.
$ nikola serve --browser INFO: serve: Serving HTTP on 0.0.0.0 port 8000... INFO: serve: Opening http://0.0.0.0:8000/ in the default web browser...
- Check out the demo content installed with the site to see what Nikola can do — and that’s not all it has to offer!
- Find out what other commands are available by using
- Read the Nikola Handbook to learn more about Nikola.
- Edit the
conf.pyfile to your liking.
- Check out themes and plugins for Nikola, or write your own.
Configuring other markup formats
Input formats other than reStructuredText need some configuration, which has been described in The Nikola Manual.
Removing demo content
When you’re done exploring, you should remove the demo content before deploying it to your server. Remove the demo stories, welcome post, demo gallery and listing manually. Run
nikola build to make them disappear from the archives. Note that this is not enough; you need to delete the now orphaned files. Nikola can do it for you — run
nikola check --clean-files. Note that this command will delete all files in the output directory it does not know about, which can be dangerous — please back up your files or find out what will be deleted by using
Hint: files in the
files/ directory are copied to the output directory as-is.
The development server (
nikola serve) should not be used outside of your local network. Instead, you should use a more serious web server. Nikola sites work on any web server which can host html files. You can use shared hosting, your own server (VPS/dedicated), GitHub Pages, or any other service that lets you host a website. For more details on deployment and related configuration, see the Deployment section in the Handbook.