blog: Setting up your Django Environment - Using virtualenv, pip and git

Posted on 13 Jul 2010 under growdjango

You’ve heard all your cool friends talking about Django and now you’re ready to join the club, but Django is a large framework with many moving parts and perhaps you’re not quite sure where you should be placing these “reusable apps” everyone keeps talking about, or not even sure what “pip” is.

Have no worries my friend! We are about to go over everything you needed to know about setting up your Django environment and getting started on projects the right way.

The three most common questions about setting up your Django project are1:

Agreed? I hope so! Let’s get straight to the questions.

How should I layout my Django project?

This is probably the most common question I have heard about Django and the short answer is: Whatever way you want. But you didn’t come here to read that, no, you came here for some suggestions.

First, the official Django site provides suggests Best Practices To Work With 3rd Party Apps which is a great start, but I don’t like how they suggest placing 3rd party apps under your project directory. Instead, we’ll use virtualenv to house any 3rd party apps.

Next, here’s a simple visual example of how you may want to lay out your project. This setup is pretty common and takes into account most setups your project may start off with, or grow into.

example.com/
    README
        Tell your team, or the world a little bit about this project. 
        Great place for a "quick use" guide
    project_directory/
        common/
            Place any application(s) that is local to this project, and isn't really a reusable app.
        templates/
            Project specific templates as well as over-riding reusable app templates.
    docs/
        Project documentation. You write documentation, right?
    static/
        Javascript, CSS, and layout images go here. Recommended to separate them as well:
        css/
        js/
        images/
    tests/
        If you have any project level tests, keep them out of your apps.
    uploads/
        If you have a user centric site they might be uploading things. 
        Keep that directory outside of your main project area.
        

There’s a simple example! This one is primarily suited for a single project. There are other great examples as well.

You will generally always want to have a static folder. Documentation and user uploads folder are more optional, but are recommended for most scenarios. In the end, setup what you feel comfortable with.

As mentioned though, it’s simply up to you. Whatever works for your team or project is the one that you should probably use. There is no real standard.

Using virtualenv and pip to organize and install Django reusable apps

The next common question is where do you place all these reusable apps? Django has a very large reusable app ecosystem which is great because you’re not re-inventing the wheel all the time.

The first common mistake is placing these applications into your own project and modifying them as you see fit. This is not recommended at all and will cause you many headaches when you want to upgrade the application or need to share your code with another team member

virtualenv is the tool most people use when working with Python/Django projects. virtualenv is a tool to created isolated Python environments so you can control exactly what application and their versions you want to run. Common use cases include:

To install virtualenv, pop into your command line shell and type:

easy_install virtualenv

Don’t worry, this is the last you’ll see of easy_install now that we have pip. (In more recent versions, pip comes bundled with virtualenv!) See Differences from easy_install for more information.

So now you have virtualenv installed and you’re ready to go! What exactly do you do now? First, you must decide where you want to store your virtual environments, personally I keep them in a hidden directory under my home. Then, we will create our actual new virtual environment.

mkdir ~/.virtualenvs
virtualenv ~/.virtualenvs/example

That’s the gist of it! Go into your new virtualenv directory and explore a bit. You’ll find it familiar to your root Python installation but with its own `site-packages` folder.

There is a great tool named virtualenvwrapper that makes working with virtualenv environments much easier and intuitive. I will be using the standard method throughout the rest of this piece, but I highly recommend this.

Now that you have this new directory, we need to actually make your Django projects use it. What we do here is activate a shell script that wraps some Python environment variables into our `PATH` variable.

source ~/.virtualenvs/example/bin/activate

You should now see your shell with the project name wrapped at the beginning of the input.

We’re almost there on using this isolated environment for our project. Next, let’s use pip to install the latest version of Django into your virtualenv.

By default, whenever you open a new shell tab/window, you must re-activate your virtualenv environment using the “source” command mentioned above. If you downloaded the virtualenvwrapper you can also use the workon projectname shortcut.

pip install Django

That’s it. virtualenv recently integrated support with pip so you don’t have to specify the virtualenv directory. You will see pip downloading Django and then unpack it, chmod some files, and work it’s magic. If you now go to the site-packages folder within your virtualenv, you will see the new installation of Django!

If pip isn’t installing into your virtualenv directory and you’ve activated your virtualenv, try using the -E flag to specify where pip should install. For example: pip install -E ~/.virtualenvs/example Django. Additionally, see Using pip with virtualenv

Great! You’ve now installed Django on it’s own isolated environment. Now if you ever have a project requiring a different version of Django you can easily put that in its own environment too. Do you get the picture now? A great way to keep away any conflicting versions!

But wait, you are hopefully asking: What if my project uses multiple applications, and I’m putting it on multiple machines? How am I supposed to remember which applications my project uses? This is ridicoulous! And so forth.

Not to worry, because pip comes with a beautiful setup using a simple requirements file to handle what applications your Django project will need. The file is simple to setup and might look something like this:

requirements.txt (Generally placed into your projects root directory.)

Django
django-registration
whoosh
-e git://github.com/grengojbo/django-piston.git#egg=django-piston

By default, pip will search PyPI for the applications listed here. As you may notice, you’re not limited to Django applications, you can place any Python package within this file and pip will handle the rest. In this case, you simply use the -r flag when installing applications.

pip install -r requirements.txt

Simple! pip will go through the file and work its magic. If it can’t find an application, it will error out with an easy to understand error message. If you are having trouble finding a packages name, you can use pip’s builtin search via pip search “query”

Finally, you will see I have a git line in there. Pip supports downloading from repositories of all kinds. I recommend reading the requirements file format page to understand how to get your project added to the file but with that line, pip will now grab the django-piston repository and set it up in my virtualenv.

At this point, you should now have a fully loaded virtualenv directory. With Django installed under there, let’s try loading up our development server. Remember, make sure you’ve activated your virtualenv directory since we’re still just working in the shell. Remember how?

source ~/.virtualenvs/example/bin/activate

If you’ve activated your virtualenv and installed Django via pip as mentioned above, you should see your Django server run. At this time you should also make sure you do not have any Django installations within the root of your Python install. If you do, I recommend removing them, as well as ensuring any projects on your system are not relying on that root install, and switching existing projects to virtualenv.

Phew, you’ve come a long way! Before we wrap up here, let’s do a quick run through of version control tools.

The final common question: Best ways to manage my code and work with others?

To be honest, I am going to assume you have some knowledge of version control. If you do not, the links to follow should guide you in your path to choosing the right one for you.

The most popular version control tools used by the Django community are git and Mercurial. In the end, there’s always going to be a battle of which is better to use, but they are both fundamentally similar.

Personally, I use git which has a great community. Some quick links:

Working with git is pretty simple. To setup your Django project to become a git repository it’s only a few lines:

git init
# Then, add your project files to the git repository
git add README
# Or, if you're adventurous (and maybe lazy), you can use the * wildcard for adding.
git commit -am "Initial commit."

Congratulations! Your project is now setup as a very simple git repository. You can put it online using services like Github mentioned above. Branching is a very common technique with git and is simple to use. Let’s say you want to work on a new feature without breaking the primary tree of code.

git checkout -b newfeature

And just like that, you’re now working on a new branch. Any changes made to this code and any commits will stay on this branch. When you’re done all your new features and tested everything up, you can merge them into your primary trunk. Think if the whole thing like a tree.

git isn’t just for Django. I know you probably know this, but I’m just going to throw it out there. You can use it with whatever language or form of media you like. I know designer friends who store their .PSD files on git to have some revision control.

Apart from that, I’m not going to delve much more into git as it’s out of the scope of this article. With git setup, you should add your entire project including the requirements.txt file for pip into a repository. Then, when you are ready to pull it onto another server you have the entire project, with all the required applications ready to go.

You’re now a Django environment superstar!

Perfect. You’ve gotten this far. You’re now using all the best tools that the community has to offer for setting up your Django environment. To summarize, here is what we did:

Thanks for getting this far. If you have any questions you can follow me on Twitter for some quick ones, or you can contact me for more indepth ones. I am happy to help!

Stay tuned as I will be writing a second article on deploying Django. I had originally written a couple articles on this, but I feel there are better ways to do it now then I have previously written. Keep an eye on for that!

1 I cannot verify these are the most common environment questions about Django, but enough time spent on Stackoverflow makes it seem like they are.

Others Posts You May Enjoy

Thanks for reading. How about leaving a comment?

blog comments powered by Disqus
Fork me on GitHub