Personal tools
You are here: Home Documentation How-Tos Using Virtualenv for a clean Grok installation

Using Virtualenv for a clean Grok installation

This How-to applies to: Any version.
This How-to is intended for: Any audience.

NOTE: As of Grok 1.2, you do not need to use virtualenv. Grok is automatically isolated from the system python environment.

Benefits of Using Virtualenv

Virtualenv is a python tool that allows you to create isolated python environments. It is great for simplifying the environment for your Grok installation so that you don't run into version or permissions problems. It can also be used as a solution for installing python packages on machines where you do not have write access to the site-packages directory.

  • It's really easy to use virtualenv
  • Virtualenv can allow you to have different Zope versions on your system (or any conflicting python software). This can be very useful if you run Plone and Grok on the same machine, or if you use a stand alone Zope version that is different from the Zope version that Grok uses.
  • Virtualenv will allow you to install Grok on a system to which you do not have write access to the system wide python directory.

Example of conflicting packages

You have already installed Zope 3.1 for a previous development task. This was installed system wide and has placed a number of packages in your site-packges directory. Grok currently requires the Zope Toolkit (ZTK). Running grokproject produces an error and aborts it's process.

Virtualenv provides a fix by allowing you to use your Python installation without the packages installed in the default site-packages directory.

What you need

A working Python installation with virtualenv and easy_install is required.

You can install virtualenv with easy_install:

$ easy_install virtualenv

If you have newer versions of Python on your system, then you can target the required version of easy_install with:

easy_install-2.6 virtualenv

Debian specific instructions

If you are using a Debian-based system, you can use the apt package management tool to install virtualenv. For Debian this is available on the unstable branch (Sid) as python-virtualenv:

# apt-get install python-virtualenv

The current stable release of Debian 4.0 (Etch) does not have the python-virtualenv package available, but does have easy_install available, so you can install it by running:

# apt-get install python-setuptools
# easy_install virtualenv


Creating a new Python sandbox

Create the virtual python environment

Run the virtualenv command to create a new, clean Python environment by the name of 'virtualgrok':

virtualenv --no-site-packages virtualgrok
This creates a directory called 'virtualgrok' with two folders within it, lib and bin. This will look like this:

NOTE: Grok 1.1 requires python 2.6 or 2.5 (2.4 deprecated) so you would have easy_install-2.5/-2.6 and python2.5/2.6.

The optional --no-site-packages switch means that none of your existing Python site-packages will be available in your new Python environment. This is desirable if you already have conflicting Python packages installed that you want to avoid (or might install such packages in the future).

Some Zope developers do not use this switch as they have installed a second Python (or sometimes many more!) separate from the system Python for developing Python web applications with. They only install the more difficult to install packages into their development Python such as PIL, XML, database and LDAP packages available and then use a separate virtual environment for each major Zope project they work on. Zope developer Lennart Regebro has termed this approach as "having both a belt and suspenders".

Activate your virtual python environment

VirtualEnv creates a shell file called activate which you can optionally use to alter your PATH environment variable so that you do not have to type the full path to your new Python (e.g. /home/username/virtualgrok/bin/python). Let's look at how you can use the source shell command with this activate file to make the new python the default:

$ echo $PATH
$ which python
$ source virtualgrok/bin/activate
(virtualgrok)$ echo $PATH
(virtualgrok)$ which python
(virtualgrok)$ deactivate

Install grokproject

Install grokproject making sure that you use the easy_install provided by your new virtual Python environment:

(virtualgrok)$ easy_install grokproject

At this point you may want to continue following the Grok Tutorial from where it leaves of with the install instructions.

Further information

Thanks to j-w from the #grok IRC channel on for much help. And to Ian Bicking for creating VirtualEnv.

Creative Commons License
This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License.

error report

Posted by Jesse Yuh at Mar 02, 2008 10:45 PM
I tryed the command as virtualenv --no-site-packages virtualgrok on Windows XP Pro. and python 2.4.4.
Then virtualenv says :
File "c:python24\lib\site-packages\virtualenv-1.0-py2.4.egg\", line 369, in call_subprocess raise OSError(OSError: Command virtualgrok\Scripts\python.exe -c "#!python\"\"\"Bootstrap setuptoo...

This is hand copy. I hope that is solved soon.

-- JY

Virtualenv and easy_install commands

Posted by Todd Matsumoto at Sep 09, 2008 02:52 AM

I've just started a virtualenv environment on my Mac 10.5, I was wondering, do I have to use easy_install, within the activated virtualenv setting? The way I understand it is, if I add a grokproject foo inside the virtualenv directory I have the following tree structure:


To me this is mixing a bunch of python stuff, with a grokproject. Is there a way to activate the virtualenv, and use that python to make a project in for example '/home/user/grokprojects/foo'?