Set up new Django project
This guide will walk you through very first steps with the Django web framework. At the end you will:
- create the environment for the project
- set up development environment
- create a new Django project
- run the web-site under Django control for the first time
Switch to the boilerplate:
git checkout bp-new-projectThis will set your working directory to the starting point for the new Django project.
A virtual environment is created on top of an existing Python installation, known as the virtual environment's "base" Python, and may optionally be isolated from the packages in the base environment, so only those explicitly installed in the virtual environment are available (see also).
python -m venv .venvThe command above will create a .venv directory within your project root, using the default Python interpreter as "base". You can choose any name you like, but consider .venv being a common name for the target directory.
You need to activate virtual environment before start using it. At the creation, the activation scripts have been deployed to the target venv directory. The location is .venv/bin for Unix-like systems (Linux-based and MacOS), and .venv/Scripts for Windows.
To activate the virtual environment execute one of the commands below, based on your operating system.
source .venv/bin/activate.venv\Scripts\activateUsually, the name of virtual environment in braces will appear in the terminal prompt, indicating it has been activated.
In the terminal session with activated venv do deactivate.
Before we start creating the Django project, the framework should be installed to the local environment. Django is
available via PyPI, as many others Python frameworks and libraries. In general you can use command
pip install <package> to install any package available in PyPI repositories.
The boilerplate project comes with all required dependencies listed in formats suitable for using with pip and poetry package managers. To install them do the command suitable for the package manager of your choice:
pip install -r requirements.txtpoetry installOr, you can install the package yourself by list them to the pip install command.
The table below lists the packages required for the very first steps with the Task Tracker training project. This list will be extended in the future.
| Package | Version | Package homepage |
|---|---|---|
| Django | ^5.0.1 | https://djangoproject.com/ |
| psycopg2-binary | ^2.9.9 | https://www.psycopg.org/ |
| python-dotenv | ^1.0.1 | https://pypi.org/project/python-dotenv/ |
Once Django framework is installed, django-admin command will become available within the project's
environment. Use startproject subcommand to generate the new project. The general syntax is:
django-admin startproject <project> [path/to/project/root]
Consider the repository to be the project's root at the same time. You can refer current directory from the terminal
as . (single dot).
Initialize the new project as:
django-admin startproject tasktracker .New files will appear:
/ |-- tasktracker/ | |-- __init__.py | |-- asgi.py | |-- settings.py | |-- urls.py | `-- wsgi.py `-- manage.py
The manage.py module will be used to manage the project. Most of the commands will be executed via this module in
the future. In short, you may consider this module the specialized and extended django-admin
for the current project.
To run the project use the runserver subcommand from the terminal. This command will be used to run
the development server on your localhost.
python manage.py runserverYou will be able see output of some like:
Django version 5.0.1, using settings 'tasktracker.settings' Starting development server at http://localhost:8000/ Quit the server with CTRL-BREAK.
Visit the URL from the output in your web-browser to see the default Django starter page.
The last, but not the least step is to apply environment variables to store sensitive data, instead of hard coding it
to the settings.py module. Open the tasktracker/settings.py and look for the line
# SECURITY WARNING: keep the secret key used in production secret!This is the reason for the python-dotenv package being installed. This package helps to read and set up
environment variables. In the project root create a new file named .env (with dot at the start). This will be
the file to store the environment variables required by the project. Fill free to use .env.example file as a
boilerplate. As for now, the only one variable to be set is DJANGO_SECRET_KEY (refer to the repository
README file
for more information on environment variables in use). Set up the value for the DJANGO_SECRET_KEY inside
of .env file, it may look some like this:
DJANGO_SECRET_KEY=tasktracker-django-project-secret-keyYou may use https://djecrety.ir/ site to generate a strong secret key for the Django project.
Make adjustments at the beginning of the tasktracker/settings.py module:
import os
from pathlib import Path
from dotenv import load_dotenv
# Take environment variables from .env file.
load_dotenv()
# Build paths inside the project like this: BASE_DIR / "subdir".
BASE_DIR = Path(__file__).resolve().parent.parent
# Quick-start development settings - unsuitable for production
# See https://docs.djangoproject.com/en/5.0/howto/deployment/checklist/
# SECURITY WARNING: keep the secret key used in production secret!
SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY")Make sure, your server has been restarted successful, and you're still able to see the Django welcoming page.