In this article you will find some useful tips regarding starting a new Django project and preparing a development environment. The steps below describes what I generally do when I’m starting a new project.
Step 1: Python Virtual Environment
If you have to maintain more than one Django project, at some point you will end up having problems with its dependencies, or with the Django version itself. The solution is to use virtualenv, which is a tool to create isolated Python environments.
It’s great because each of your Django project can live inside its own Python environment.
If you don’t have it yet, you can install it using pip:
The basic usage of virtualenv would be, inside the folder you want to place your project, execute the following command:
The instruction above will create a Python environment named
simple_django_skeleton. In the end of the day, it’s just a folder with a Python installation inside. We will place our Django project folder and all its dependencies inside this folder.
Now, inside the
simple_django_skeleton folder, activate the environment:
You will notice that the name of the active virtualenv will now appear on the left of the prompt. Your terminal should look like something like this:
Step 2: Git Remote Repository
I prefer to create the remote repository first on GitHub, and then clone it into my development environment. It’s cleaner this way.
simple_django_skeleton folder, clone your recently created repository:
Your folder structure should look like this:
Step 3: Install Django
virtualenv activated, install Django using
Step 4: Initialize the Project
simple-django-skeleton folder, which is the git repository, initialize the Django project:
Notice the dot in the end of the
startproject command. It will start the project in the current folder.
Step 5: Install python-decouple, Unipath and dj-database-url
I use those three packages on all my Django projects. Python Decouple is a package to separe configuration variables from the source code (in case you missed our last week article about Python Decouple, you can read it here). Unipath will help you writing relative paths. Finally, dj-database-url will give you a cleaner way to write your database url.
Step 6: Create a requirements.txt file
It’s important to keep track of your project’s requirements. Specially if you are gonna make it available for the public:
Step 7: Add basic settings
First, remove the
os import and the
BASE_DIR definition and add the following imports:
Define the static and media stuff, so Django won’t have problems finding your css/js files:
Define template folder, so Django will render your templates correctly:
Decouple your settings params so you don’t commit any sensitive data or environment-specific param:
.env file in the project root:
Make a copy of your
.env file, name it
.env.example and add some sample data. This will help people who will run your project later on, as we will make Git ignore the
Step 8: Create static and template folders
I like to create a folder to place project-wide templates (e.g. base.html) and static files inside the project folder:
To get things started I usually create a simple
Step 9: Create a .gitignore file
I use the GitHub’s Python .gitignore. Then I update it with the following:
.DS_Store is a OSX file that’s automatically created by the OSX file explorer, Finder.
Step 10: Do a initial commit
Now we have a basic setup, we can commit our starting point:
Step 11: Migrate
Migrate the Django models, in case you will be using
Step 12: Create first App
If the project’s model is not clear for me in the beginning, I usually create an app called core. If it starts to grow, I refactor the app.
One thing to keep your apps well organized, is to create a folder called
apps, then you place all your Django Apps inside it. Also, I like to create my Apps inside the project folder, so it stays in the project’s namespace.
__init__.py is required to properly import the apps.
Add it to
Edit your project’s
template folder inside the app core, and then inside create a folder named
core and a file for our homepage
Edit the app core
views.py adding our first view:
That’s it! As soon as I reach this point and got everything working fine, I start the development.
If you want to see the source code of this sample project, you can grab the source code on GitHub simple-django-skeleton.