Start a Django project

Problem

You want to start a Django project to develop your application or web site.

Solution

Use the django-admin executable or django-admin.py script along with the startproject sub-command to create a Django project. After installing Django, both the previous executable and script should be accessible from any directory on your system (e.g. installed under /usr/bin/ or /usr/local/bin/). Note that both the executable and script offer the same functionality, therefore I will use the django-admin term interchangeably going forward.

How it works

The django-admin startproject command creates a Django project structure with a project name given as an argument. For example, you can execute django-admin startproject coffeehouse to create project called coffeehouse or django-admin startproject sportstats to create a project called sportstats.

A Django project name can be composed of numbers, letters or underscores. A project name cannot start with a number, it can only start with a letter or underscore. In addition, special characters and spaces are not allowed anywhere on a project name, mainly because Django project names serve as a naming convention for directories and Python packages.

Upon executing django-admin startproject <project_name>, a directory called <project_name> is created containing the default Django project structure. The default Django project structure is illustrated in listing 1.

Listing 1 - Django project structure

+<BASE_DIR_project_name>
|
+----manage.py
|
+---+-<PROJECT_DIR_project_name>
    |
    +-__init__.py
    +-settings.py
    +-urls.py
    +-wsgi.py

If you inspect the directory layout, you'll notice there are two directories with the <project_name> value.

The top level one I will refer to as the BASE_DIR, which includes the manage.py file and the other sub-directory based on the project name. The second level sub-directory -- which includes the __init__.py, settings.py, urls.py and wsgi.py files -- I will refer to as the PROJECT_DIR.

The manage.py file inside the BASE_DIR is used for a series of project specific tasks that I'll describe as we move forward. The files inside PROJECT_DIR are described in the following list:

Note Rename a project's BASE_DIR to avoid confusion

Having two nested directories with the same name can lead to confusion. This can be specially true if you deal with Python package import issues. To save yourself trouble, I recommend you rename the BASE_DIR to something different than the project name (e.g. rename, capitalize or shorten the name to make it different than the PROJECT_DIR).

Note Do not rename the PROJECT_DIR

The PROJECT_DIR name is hard-coded into some of the project's files (e.g. settings.py and wsgi.py) so do not change its name. If you need to rename the PROJECT_DIR it's simpler to create another project with a new name.

Now that you're familiar with the default Django project structure, lets see the default Django project on a browser. All Django projects have a built-in web server to observe an application on a browser as changes are made to project files. Placed in the BASE_DIR of a Django project -- where manage.py is -- run the command python manage.py runserver as illustrated in listing 2.

Listing 2 - Start Django development web server provided by manage.py

[user@coffeehouse ~]$ python manage.py runserver
Performing system checks...

System check identified no issues (0 silenced).

You have 13 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, sessions.
Run 'python manage.py migrate' to apply them.

May 23, 2017 - 22:41:20
Django version 1.11, using settings 'coffeehouse.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

As illustrated in listing 2, the command python manage.py runserver starts a development server on http://127.0.0.1:8000/ -- this is the local address on your system. Don't worry about the 'unapplied migration(s)' message for the moment, I'll address it the next recipe on setting up a database. Next, if you open a browser and point it to the address http://127.0.0.1:8000/ you should see the default home page for a Django project illustrated in figure 1.

Default home page for a Django project
Figure 1.- Default home page for a Django project

Sometimes it's convenient to alter the default address and port for Django's development web server. This can be due to the default port being busy by another service or the need to bind the web server to a non-local address so someone on a remote machine can view the development server. This is easily achieved by appending either the port or full address:port string to the python manage.py runserver command, as illustrated in listing 3

Listing 3 - Start Django development web server on different address and port

# Run the development server on the local address and port 4345  ( http://127.0.0.1:4345/ )
python manage.py runserver 4345
# Run the development server on the 96.126.104.88 address and port 80 ( http://96.126.104.88/ )
python manage.py runserver 96.126.104.88:80
# Run the development server on the 192.168.0.2 address and port 8888 ( http://192.168.0.2:8888/ )
python manage.py runserver 192.168.0.2:8888