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:
- How should I layout my project?
- Where do I put the reusable apps I download for Django? (virtualenv, pip)
- What’s the best way to manage my code and work with others? (git)
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.
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:
- Creating a virtual environment for a new version of Python to test your project on
- Testing out the newest version of an application without breaking your existing infrastructure
- Not interfering with other projects. Multiple projects using various versions of Django? No problem!
To install virtualenv, pop into your command line shell and type:
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.
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?
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:
- git ready is a great way to learn git with small tips. If you’re ever stuck and not sure how to do something with git, this is a good place to start. There is also the irc channel #git on irc.freenode.net which is extremely helpful.
- github is the git repository site. With dozens of great features, a huge community and a completely reliable service it’s a great place to put up your first Django project or just browse the thousands available for use out there.
- git official website is the place to go to get git, see a quick demo of how it works, and enjoy their awesome tree eating mascot.
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:
- We first talked about a basic project layout. Understanding not to place reusable applications into your project directory among other conventions.
- We installed and setup our first isolated Python environment using virtualenv. With this, we are now able to create multiple projects using a variety of Python packages without worrying if the one we install will cause any conflicts with previous projects.
- We learned the basic usage of pip and its requirements file. pip makes it easy to install and upgrade Python packages, and integrates very well with our virtualenv setup.
- We quickly ran through git and some common uses of it when working on not just a Django project, but any project.
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.