If you have worked with Django for any amount of time you have probably seen many articles about how to setup your development environment the “right way”. It seems like everyone has their own idea of how to do this and it can range from only slightly different to wildly different. Today I am going to explain how I setup my environment, but instead of just telling you to do it my way I will also explain the choices behind doing things the way I do.

Top Level Directory

Let’s start by moving into whatever folder you use for development. In my case I will being using ~/Projects . The first obvious thing you will need to do is create a new folder to house your project:

This is the topmost level folder that our project will use. This folder will also act as a utilities folder to hold meta data and other useful data about our project. This kind of structure is especially useful if you plan on sharing your project on gitlab or github. Generally I include the following items:

• requirements folder — allows you to use multiple requirements files. Extremely useful for testing multiple versions of Python, Django or cross platform (Windows, Unix, Dev, Prod, etc)
• docs folder — Every project should have documentation.
• README file — Gives a brief overview of your project.
• Django Project folder — This is the actual folder your django code lives in. In this case I will be using tutorial.
• a setup file (only if developing a django app) — If it is installable through pip you’ll need one of these
• a Changelog — Helps users get up to date on your project quickly
• a .gitignore file — Keep your project clean by telling git what not to stage

You may end up needing more files or folders if you plan on adding more services, like automated test runners or CI integration, but this is generally where you should place those kinds of files. This allows you to completely separate your files that do not run the project from the files that actually do the work.

This is also the folder which you should initialize git into. If you are not versioning your project in some way, you really should be.

Great so what does our project look like so far:

Using a Virtual EnvironmentTo be completely honest this could be a separate article on it’s own, but we will quickly review this issue here.

To be brief Python doesn’t handle dependencies in the best way. When you run something like pip install django Python installs Django in your global Python Path. You can find out what your Python Path is by running:

Now the problems begin when you try to install a different version of Django. If you run just one project this may not be a problem, but sometimes I can have 10–20 different Django projects I’m working on at different times in a week. Now imagine having to reinstall Django to get a different version every single time I want to work on a different project. Now this may not seem so bad, but consider once you start building up other dependencies, and those dependencies also have dependencies. You will waste a lot of time reinstalling your deps over and over.

There is a solution to this problem though! You can use what are called virtual environments. This allows you to modify where pip installs your deps so you can have multiple copies on your machine that different projects can use. Usually you create 1 or more virtual environments for each project.

Now there are multiple projects that allow you to do this, the most popular being virtualenv although some people now prefer Python3’s built in version. Personally I think virtualenvwrapper is the best, simplest solution. virtualenvwrapper offers a number of extra features such has quick access commands (mkvirtualenv, rmvirtualenv, workon) and a number of hooks to allow your own custom workflow. You are free to decide on your own which you prefer, but from my personal experience virtualenvwrapper works better than other alternatives.

You can install virtualenvwrapper through pip:

Then you just need to add a few quick lines to your rc file (usually ~/.basrc) and start a new virtual environment:

Note: if you have multiple versions of python on your system and want to use python3, you can specify this like so:

export WORKON_HOME=... just tells virtualenvwrapper where you want to store all of your configuration for your virtual environment:

As mentioned previously, virtualenvwrapper also provides mutliple utility functions:

• mkvirtualenv (name) — creates a new virtual environment under the given name
• rmvirtualenv (name) — removes a virtual environment of the given name
• workon (name) — starts up a virtual environment of the given name
• There are a multitude more commands that are well beyond the the scope of this tutorial, if you do decide to use virtualenvwrapper make sure you get the most out of it.

Starting your Django Project

Almost 1,000 words in and were finally going to start some Django! First install Django and runt he startproject command:

This will run Django’s basic startup command and install all of the basic files you need. By now your project should look like this:

So Now when you start creating apps it should be in the tutorial folder. Some people advocate placing apps in other folders, but I advise against doing this.

Closing Thoughts

I’ve played around with a lot of different setups when I ran this tutorial for DjangoCon 2017 and for Frostburg State University. I played with setups like cookiecutter and found it to just be to much for a beginner. As a reaction to that I stripped out everything that you don’t need. This is a kind of bare metal setup that provides just what a beginner needs and nothing more

.With that I hope you enjoyed this and come back on Monday when I will be covering:

• how to start an app in django
• how to break apart your code into separate files
• what each of the files in an app do