You want to start a Django project to develop your application or web site.
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/local/bin/). Note that both the executable and script offer the same functionality, therefore I will use the
django-admin term interchangeably going forward.
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
django-admin startproject sportstats to create a project called
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.
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.
If you inspect the directory layout, you'll notice there are two directories with the
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
wsgi.py files -- I will refer to as 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:
__init__.py.- Default Python file that allows Python packages to be imported from directories where it's present. Note
__init__.pyis not a Django specific file, it's a generic file used in almost all Python applications.
settings.py.- Contains the configuration settings for the Django project.
urls.py.- Contains URL patterns for the Django project.
wsgi.py.- Contains WSGI configuration properties for the Django project. Note WSGI is the recommended approach to deploy Django applications on production (i.e. for the public). You don't need to setup WSGI to develop Django applications.
| Rename a project's |
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
|Do not rename the |
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.
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.
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