Skip to main content

A First Project

Projects vs. Applications​

Django distinguishes projects from applications. An application is a Python package (that is, a folder that contains Python files) with a specific structure. A project is, in addition to a Python package, a set of applications with a common configuration. For example, different applications usually use the same database configured in a single project.

Suppose you have to develop a website with a news section and a shop section. You could create a project with two applications: news and shop. This would be a good decision for two reasons: first, these two applications do very different things, so it makes sense that they do not depend on each other. Second, by having two independent packages, they can be reused in other projects. If you now need to create a website with a forum and a shop section, you just need to write the forum application, since shop can be reused in the new project. For sake of simplicity, however, in this tutorial our websites (projects) will contain only one application.

Starting a New Project​

To create a new project, open the terminal in your favourite directory and run:

django-admin startproject myproject

This command will create a new project (and a new directory) with the name myproject. If you enter the the newly created directory, you will see that there is another directory of the same name and a file called manage.py. Within the myproject/myproject directory you will configure different aspects of your site, such as URL patterns and database connections. myproject/manage.py is a tool that allows you to execute many operations on the project during the development of your website.

In the same terminal you just used, move to the new myproject directory and then launch the website as follows:

cd myproject
python manage.py runserver

You will probably see a message regarding unapplied migrations. We can safely ignore that for now.

Once this is done, open http://127.0.0.1:8000/ in the web browser and you should see something more or less like this:

Django Successfully Installed

If so, congratulations! You have your first (empty at the moment) Django project running. The runserver command starts a web server at your local IP address (127.0.0.1) and port 8000 so you can access your site during the development stage. This web server is written in Python and is not suited to be used in production (that is, when you upload your site to a web hosting). In the production stage, one of the web servers mentioned above (Apache, NGINX, IIS, etc.) is usually configured to run our Django site. We will address these issues in the last chapter.

Let's add some functionality to the project by creating a new application. To do this, shutdown the web server by pressing CTRL + C (Windows) or CTRL + D (macOS/Linux) in the terminal and then write:

python manage.py startapp myapp

This command will create the myapp folder with several files inside, which we will take care of as we progress with the tutorial. To tell Django that the myapp application is part of the myproject project, you need to edit the project configuration file myproject/myproject/settings.py and add your application like this:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'myapp.apps.MyappConfig'  # <-- Add this element.
]

As you may have noticed, the project created via django-admin startproject includes some default applications (django.contrib.admin, django.contrib.auth, etc., which we will mention later). For now, the important thing is to remember to include your application by adding the path to the MyappConfig class inside the myapp/apps.py file, which was created automatically by the python manage.py startapp command.

Finally, start the development server again, which must be running for your site to respond:

python manage.py runserver
note

The web server started by the runserver command will take care of reloading your code every time you make changes to the files in your project or applications. However, on some occasions, particularly when syntax errors occur, it will be necessary to restart it manually by typing the above command again.