Django: Setting up Django virtual environment via python Virtualenv with Eclipse. Quick guide.

Hi! Let's talk about Django ways to code. First you have to have environment installed for work with Django. Today I'll try to show you my way of using virtual environment (python virtualenv).
It's ok to handle package dependencies in Django apps by simply manually putting libraries, are in need for your project, into project PYTHONPATH. It's an easy way to do it. BUT what if you would like to make another project with this environment (e.g. the same modules, plugins or app's set)... You will have to add all those modules to your new project. Another issue that if would like to code for existing project, like for e.g. open someone's work and add some modules to it. Virtualenv is a newly fashioned package which aims to combine the best features of a workingenv with a virtual Python install. Also you can say that it is a tool to create isolated in a sandbox Python environments. So... This article is about how to set up, run and connect to Eclipse new django project in a few minutes, using virtualenv and Django.

Install virtualenv

Installing virtualenv is easy on a Linux or Mac system, but the instructions that follow are MAC (OS X 10.7) specific. First you’ll need setuptools. It's an extremly handy programmers script to install new python modules in 'Plug'n'Pray' way. You need to get setuptools installed from for e.g.:

- Download the appropriate egg for your version of Python (e.g. setuptools-0.6c9-py2.7.egg). Do NOT rename it.
- Run it as if it were a shell script, e.g.:

sh setuptools-0.6c9-py2.7.egg 
Setuptools will install itself using the matching version of Python (e.g. python2.7), and will place the easy_install executable in the default location for installing Python scripts (as determined by the standard distutils configuration files, or by the Python installation).

Now you have a nice way to install python packages. Let's install virtualenv. Now you only have to type:

sudo easy_install virtualenv
Sudo commend is because you need root to make some system changes. Now you can jut do virtualenv ENVNAME.

Create new virtualenv

Now that you have all system apps installed. Let's create you a new virtualenv. has a good extended (but still brief) manual on commends and basic configurations. Change directory to place in where you keep your projects. (For me it's cd /Users/username/developer/tutorial/django_projects/). Now you can run:

virtualenv --no-site-packages latest_django_venv
In this case I’ve chosen latest_django_venv as my virtual environment's name. The —no-site-packages command tells virtualenv not to symlink the global site packages into my local environment, just take the Python basic libraries set. This is important, because it helps us avoid the dependency difficulties mentioned above. As a result you'll probably see something like this:

New python executable in latest_django_venv/bin/python
Installing setuptools............done.

Install Django

Virtualenv creates its own Python and easy_install binaries, which means you can install/run things in your environment. Let’s install Django using your newly created environment:

./latest_django_venv/bin/easy_install django
You will probably see a new Django installation to your dir like so for e.g.:

Searching for django
Best match: Django 1.3
Processing Django-1.3.tar.gz
Running Django-1.3/ -q bdist_egg --dist-dir /var/folders/Lc/LczB6LACE-ChJ8TIuHk4Jk+++TI/-Tmp-/easy_install-RLkEvA/Django-1.3/egg-dist-tmp-S2BxFN
zip_safe flag not set; analyzing archive contents...
django.conf.__init__: module references __file__
django.utils.unittest.loader: module references __file__
django.views.i18n: module references __file__
Adding Django 1.3 to easy-install.pth file
Installing script to /Users/username/developer/tutorial/django_projects/latest_django_venv/bin

Installed /Users/username/developer/tutorial/django_projects/latest_django_venv/lib/python2.7/site-packages/Django-1.3-py2.7.egg
Processing dependencies for django
Finished processing dependencies for django
Now finally you have everything set up with Django. You may also setup any other your packages at this stage like MySQL or iPython. I will not cover those things and it's up to you... It's also good idea to add your virtualenv directory to .gitignore file, cause you probably don't want your virtualenv uploaded to upstream.

Run Django

Now that you have everything setup you can create new Django app. You'll probably skip this step in case you setting up environment for the existing project.

Note that you must use your virtualenv binaries instead of system one's. It's a bit tricky to remember at the exact needed moment sometimes. Let's type:

./latest_django_venv/bin/ startproject newapp

Here newapp is your project name.  Note that we used django-admin script from newly created virtualenv binaries.

Now we came to almost obvious step to run Django server. Let's enter newly created app dir  and run it like so:

cd newapp
../latest_django_venv/bin/python runserver
You will probably see server running with no errors.
Let's check the browser pointed at Ta-Da!

Now you may add it to your Eclipse project. 

Connect to Eclipse

Now that you have everything working let's try to add some GUI to this method. I use Eclipse with PyDev installed like was described in my previous article. So I just add add myself a new interpreter to it. If you need to setup eclipse from scratch try to read this article. Maybe it will help you to workout something... Nevertheless Let's add a new Python Interpreter to our Preferences > PyDev > Interpreter - Python settings. You must hit New... and specify a path to your newly made virtualenv. You will see something like so:

Now hit ok and select what have to be indexed. Note that you have to hit Select All at this step. It will get "lib" folder from root python install. It's OK, because virtualenv does not copy lib folder to new environment by default. You will probably see something like so:

And finally we received new interpreter in our Ecplipse environment:

Now upon new project creation (or existing project) you can select this interpreter to use in it. You will use Project run/debug configuration and Interpreter tab there to select your new virtualenv interpreter:

Hope this article will help someone to setup Eclipse to work with Virtualenv and Django.  And now, as always: Thoughts/suggestions? Please drop me a comment here...


  1. Thanks for a handy and concise article. I'd like to know what to look out for if I set up a new virtualenv for an *existing* Django project I'm already developing? so far, I can't find any documentation on this...

  2. Well basicly you do not need anything.
    Just make:
    1. "virtualenv test --no-site-packeges" somewhere. Where "test" is your virtualenv name.
    2. run your new virtualenv like so:
    "source test/bin/activate"

    Now you are working in some kind of emulation of python environment. You can check it by "(test)" prefix before your shell command string. You can do all the things you usually do in this console now... Like do "easy_install django==1.3.1" or usually "pip install -r requirements.txt" and so on...

    What is not understandable?
    Main thing ghere is that you have to do "source test/bin/activate" every time you run new console and want to work with your django project, for e.g. "python runserver" and so on...

  3. Thanks for taking the time to share your knowledge. It's very much appreciated.

  4. This comment has been removed by a blog administrator.

  5. I dont know what I am doing wrong but mine keeps returning 'cannot find sdist setuptools..'. Any idea of what I can do?

    1. you need to install setuptools.


Post a Comment

Popular posts from this blog

Run Flask with Debug in PyCharm

Python converting PDF to Image

Django: Resetting Passwords (with internal tools)