Installing PyBlosxom with CGI

Author: PyBlosxom Development Team
Version: install_cgi.txt 1099 2007-08-11 15:43:22Z willhelm
Copyright: This document is distributed under the MIT license.



While there are many ways to install PyBlosxom, the most common one is to install PyBlosxom as a CGI script for a single user. This installation guide will cover that. For other ways to install PyBlosxom, refer to the docs directory, mailing lists and the web-site.

This installation assumes you have some understanding of CGI, Apache configuration, and know how to manipulate files and directories. If this doesn't sound like you, maybe you should get a friend to help out or ask for help on the pyblosxom-users mailing list. Details of the mailing list are on our web-site on the Contact us page.


A note about upgrading PyBlosxom:

If you are upgrading your version of PyBlosxom, follow the instructions here and also read the README that comes with your PyBlosxom tarball for differences between this version and the previous versions. The README file contains instructions on updating your file, templates, and other parts of your PyBlosxom installation which you will have to do by hand.

Pre-requisites for installing PyBlosxom

You will need:

Additionally, if you are running PyBlosxom on Windows, you will also need:


You can find versions of PyBlosxom by going to the Download link at .

Download the latest PyBlosxom .tar.gz file.

Installing PyBlosxom

Installing PyBlosxom should take 5-10 minutes depending on what state your system is currently in. The installation consists of seven steps. Tweaking, styling, and adding content to your blog is covered afterwards and in other parts of the documentation.


Create a working temporary directory, move the PyBlosxom tar ball into it, and then untar the tar ball (something like tar -xzvf pyblosxom.version.tar.gz).

Install as library or not

There are two ways to install PyBlosxom on your system:

  1. You can install PyBlosxom as a Python library. To do this, change directory into the pyblosxom directory and run:

    python install

    After you do this, PyBlosxom will be installed as a Python library and you can move on to Setting up a blog.

  2. If you don't want to or can't install PyBlosxom as a Python library, just untar it into your directory and be sure to follow the instructions on setting the codebase parameter later.

Setting up a blog

To set up a blog do the following:

  1. Copy the and pyblosxom.cgi files from the web/ directory into your cgi-bin/ directory or some directory that has CGI permissions.

  2. First create a directory for holding all your PyBlosxom files. Call this directory myblog/ and put it in your userdir.

    Then create a sub-directory entries/ under myblog/.

    The entries for your blog are text files in your datadir. The datadir can contain directories each of which will be a category for PyBlosxom. In general, it's good to use one-word names that don't have spaces or punctuation in them for your directories.

    Then create a sub-directory flavours/ under myblog/.

    Flavours are collections of template files for a single look and feel for your blog. You can store these flavours in the flavourdir.

    Then create a sub-directory plugins/ under myblog/.

    This directory will hold plugins that augment and extend the PyBlosxom's default behavior to meet your specific needs.

    The resulting tree would look like this (if your name was joe):

       |- myblog/
            |- entries/
            |- flavours/
            |- plugins/
  3. Open the file up in your favorite editor. Go through and change the values of the configuration settings according to the instructions in the file.

    Make sure to set:

    • the datadir property to the datadir directory you created,
    • the flavourdir property to the flavourdir directory you created,
    • the plugins_dir property to the plugins directory you created,
    • and load_plugins to the empty list [ ].


    If you did NOT install PyBlosxom as a Python library, then you must also set the codebase property to the directory you untarred PyBlosxom into. This should be the directory that holds the Pyblosxom directory (note the case!).

    Plugins will require you to add new variables to your file in order to direct the plugin's behavior. Additionally, you can add variables to your and these variables will be available to you in your flavour templates.

  4. You want to verify that your blog is set up correctly. Change directory into your cgi-bin directory and run from the command line:


    PyBlosxom will go through a series of checks on your file to make sure that things are set up correctly and that required properties are set.

    If there are any problems, follow the instructions that it gives you.


    Because you're running this check from the command line, there could still be problems with your setup. However, if you get through the verify step, then it's likely any further problems are related to your web-server setup and whether it can execute pyblosxom.cgi.

  5. Now it's time to write your first post and test your blog. Change directories to your datadir, launch your favorite editor and create a file called firstpost.txt. Copy the following text into it:

    This is my first post
        This is my first post with PyBlosxom.

    The first line "First Post" becomes the title of the blog entry. The date of the blog entry is the mtime on the file. The body of the blog entry starts with the HTML paragraph tag in the second line and extends to the end paragraph tag in the last line. Your blog entries can be as long as you want. The first line is plain text--everything after that is HTML.


    If you want to use a different markup like reST or Textile or Moinmoin or something like that, see the documentation on Writing Entries for how to set that up.

    Open up a web-browser and go to the URL http://your_server_here/path/to/cgi-bin/pyblosxom.cgi

    If you're running GNU/Linux with Apache and you have user folders set up and your username was joe, then the url for your PyBlosxom blog might be something like this:

    If everything is configured correctly, you should see your first post rendered with the default HTML flavour. If not, you'll either see a Python stack trace or a message along the lines of Internal Server Error. See below for help on trouble-shooting.


We're going to try to break this down a bit into categories. Bear with us and keep trying things. If you have problems and have gone through this section to no avail, then come talk to us on the Pyblosxom users list. Details of the mailing list are located at our Contact us page.

Running ./pyblosxom.cgi doesn't work

First, you should check to see if you have Python installed on your system. If not, then please install Python.

If Python is installed on your system, make sure the first line in pyblosxom.cgi points to your Python interpreter. If not, fix that and try running ./pyblosxom.cgi again.

If Python is installed on your system and the first line of pyblosxom.cgi is correct, then check for permissions issues: pyblosxom.cgi is a script--so it needs execute permission in order to function. If those aren't set, then fix that and try running ./pyblosxom.cgi again.

I see a HTTP 404 error when I try to bring up my blog

When you try to look at your blog and you get a HTTP 404 error, then you're using the wrong URL. Are you futzing with .htaccess? Does your server allow you to run CGI scripts? Do other CGI scripts work? Does the URL you're trying to use to access PyBlosxom look like other URLs that work on your system?

I see a HTTP 500 error when I try to bring up my blog


Please read the installation chapter:

At this point, running ./pyblosxom.cgi at the command prompt should work fine. If you haven't done that and you're busy trouble-shooting, go back to the installation guide and make sure you did all the steps.

When you try to look at your blog in a web-browser and get a HTTP 500 error, the first thing you should do is uncomment the line in pyblosxom.cgi (remove the # at the beginning of the line) that looks like this:

#import cgitb; cgitb.enable()

so that it looks like this:

import cgitb; cgitb.enable()

Then refresh the page in your browser. If the problem is with PyBlosxom and not your web-server, then you should see a pretty traceback that will help you figure out what the specific problem is.

If it doesn't make any sense to you, you can copy and paste that into an email to the pyblosxom-users mailing list and we're in a better position to help you out.

If you don't see a traceback, then you either have a configuration problem with your web-server or a configuration problem with Python. The first thing you should do is check your web-server's error logs. For Apache, look for the error.log file in a place like /var/logs/apache or /var/logs/httpd.

Does the account your web-server runs as have execute access to your pyblosxom.cgi script? If your web-server does not have the permissions to read and execute your pyblosxom.cgi script, then your blog will not work.

Do you have plugins loaded? If you do, try unloading all your plugins and see if the problem persists. Sometimes there are issues with plugins that only show up in certain situations.

I have other issues

Try changing the renderer for your blog to the debug renderer. You can do this by setting the renderer property in your file to debug. That will show a lot more detail about your configuration, what the web-server passes PyBlosxom in environment variables, and other data about your blog that might help you figure out what your problem is.

UGH! My blog looks UGLY!

Read the chapter on Flavours and Templates to help you out.

I hate writing in HTML!

That's ok. PyBlosxom supports entry parsers which allow you to format your blog entries in any formatting markup that someone has written a plugin for. See the documentation on Writing Entries for more information.


That's it! If you have problems, visit our web-site and read through the updated documentation including the Trouble-shooting section of the PyBlosxom Manual.

Happy blogging!

-- PyBlosxom Development Team