Chapter 1: Initial Set Up

This chapter focuses on configuring your Windows or macOS computer to work on Django projects. You are probably eager to dive right in, but setting up your computer correctly now will save you a lot of pain and heartache later.

You are probably eager to dive right in and start using Django, but configuring your computer now for Django development is a one-time task that will pay many dividends in the future. It is important to be comfortable with the command line and shell commands, understand how to use virtual environments, install the latest version of Python, use a text editor, and work with Git for version control. By the end of this chapter, you will have created your first Django project from scratch and be able to create and modify new Django projects with just a few keystrokes.

The Command Line

The command line is a text-only interface that harkens back to the original days of computing. If you have ever seen a television show or movie where a hacker is furiously typing into a black window, that's the command line. It is an alternative to the mouse or finger-based graphical user interface familiar to most computer users. Regular computer users will never need to use the command line. Still, for software developers, it is a vital and regularly used tool necessary to execute programs, install software, use Git for version control, and connect to servers in the cloud. With practice, most developers find that the command line is a faster and more powerful way to navigate and control a computer.

Given its minimal user interface--just a blank screen and a blinking cursor--the command line is intimidating to newcomers. There is often no feedback after a command has run, and it is possible to wipe the contents of an entire computer with a single command if you're not careful: no warning will pop up! As a result, use the command line with caution. Refrain from mindlessly copying and posting commands you find online; rely only on trusted resources.

In everyday usage, multiple terms refer to the command line: Command Line Interface (CLI), console, terminal, shell, or prompt. Technically speaking, the terminal is the program that opens up a new window to access the command line, a console is a text-based application, and the shell is the program that runs commands on the underlying operating system. The prompt is where commands are typed and run. It is easy to be confused by these terms initially, but they all essentially mean the same thing: the command line is where we run and execute text-only commands on our computer.

The built-in terminal and shell on Windows are both called PowerShell. To access it, locate the taskbar next to the Windows button on the bottom of the screen and type in "PowerShell" to launch the app. It will open a new window with a dark blue background and a blinking cursor after the > prompt. Here is how it looks on my computer.

PS C:\Windows\System32>

Before the prompt is PS, which refers to PowerShell, the initial C directory of the Windows operating system, followed by the Windows directory and, within it, the System32 directory. Don't worry about what comes to the left of the > prompt at this point: it varies depending on each computer and can be customized later. The shorter prompt of > will be used going forward for Windows.

At this point, we need to navigate to the users directory, so enter the command cd \users followed by the Enter key to change directories (cd) into users.

PS C:\Windows\System32> cd \users
PS C:\Users>

On macOS, the built-in terminal is called Terminal. Open it via the Spotlight app: simultaneously press the Command and Space bar keys and then type in "terminal." Alternatively, open a new Finder window, navigate to the Applications directory, scroll down to open the Utilities directory, and double-click the Terminal application, which opens a new screen with a white background by default and a blinking cursor after the % prompt. Don't worry about what comes to the left of the % prompt. It varies by computer and can be customized later on.

Wills-Macbook-Pro:~ wsv%

Since 2019, the default shell for macOS has been zsh, which uses the % prompt. If you see $ as your prompt, you are using the previous default macOS shell, Bash. While most of the commands in this book will work interchangeably, if your computer still uses Bash, it is recommended to look online at how to change to zsh via System Preferences.

Note: In this book, we will use the universal $ Unix prompt for all shell commands rather than alternating between > on Windows and % on macOS.

Shell Commands

There are many available shell commands, but developers generally rely on half a dozen commands for day-to-day use and look up more complicated commands as needed.

In most cases, Windows (PowerShell) and macOS commands are similar. For example, the command whoami returns the computer name/username on Windows and the username on macOS. As with all shell commands, type the command itself followed by the return key. Note that the # symbol represents a comment not executed on the command line.

# Windows
$ whoami
wsv2024/wsv

# macOS
$ whoami
wsv

Navigating within the computer filesystem is a frequent command-line task. On Windows and macOS, the command pwd (print working directory) outputs the current location within the file system.

# Windows
$ pwd

Path
----
C:\Users

# macOS
$ pwd
/Users/wsv

You can save your Django code anywhere, but we will place our code in the desktop directory for convenience. The command cd (change directory) followed by the intended location works on both systems. On Windows, you first need to change directories into your user directory, which is represented by the whoami command. On my computer, it is wsv, but yours will be different.

# Windows
$ cd wsv
$ cd onedrive\desktop
$ pwd

Path
----
C:\Users\wsv\onedrive\desktop

# macOS
$ cd desktop
$ pwd
/Users/wsv/desktop

Tip: The > key on Windows and tab on macOS will autocomplete a command, so if you type cd d and then hit > or tab, the rest of the name will be filled in automatically.

To create a new directory, use the command mkdir followed by the name. We will create a code directory on the desktop and a new directory named ch1-setup within it.

# Windows
$ mkdir code
$ cd code
$ mkdir ch1-setup
$ cd ch1-setup

# macOS
$ mkdir code
$ cd code
$ mkdir ch1-setup
$ cd ch1-setup

You can check that it has been created by looking on your desktop or running the command pwd.

# Windows
$ pwd

Path
----
C:\Users\wsv\onedrive\desktop\code\ch1-setup

# macOS
$ pwd
/Users/wsv/desktop/code/ch1-setup

Tip: The clear command will clear the terminal of past commands and outputs, so you have a clean slate. As we've discussed, the tab command autocompletes the line. The↑ and ↓ keys cycle through previous commands to save yourself from typing the same thing over and over again.

To exit, you could close the terminal with your mouse, but the hacker way is to use the shell command exit instead, which works by default on Windows; on macOS, the Terminal preferences need to be changed. Click Terminal at the top of the screen, then Preferences from the dropdown menu. Click on Profiles in the top menu and then Shell from the list below. There is a radio button for "When the shell exits." Select "Close the window."

$ exit

With practice, the command line is a far more efficient way to navigate and operate your computer than a mouse. You don't need to be a command line expert to complete this book: I will provide the exact instructions to run each time. But if you are curious, a complete list of shell commands for each operating system is available at ss64.com.

Install Python 3 on Windows

On Windows, Microsoft hosts a community release of Python 3 in the Microsoft Store. In the search bar at the bottom of your screen, type in "python" and select the result for Python 3.12 on the Microsoft Store. Click on the blue "Get" button to download it.

To confirm that Python is installed correctly, open a new Terminal window with PowerShell and type python --version.

$ python --version
Python 3.12.3

The result should be at least Python 3.12. Then, type python to open the Python interpreter from the command-line shell.

$ python
Python 3.12.3 (v3.12.3:f6650f9ad7, Apr  9 2024, 08:18:47) 
 [MSC v.1937 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> 

You can exit the Python interpreter by typing either exit() or Ctrl-Z plus Return.

Install Python 3 on Mac

On Mac, the official installer on the Python website is the best approach. In a new browser window, go to the Python downloads page and click on the button underneath the text "Download the latest version for Mac OS X." As of this writing, that is Python 3.12. The package will be in your Downloads directory: double-click on it to launch the Python Installer, and follow the prompts.

To confirm the download was successful, open a new Terminal window and type python3 --version.

$ python3 --version
Python 3.12.3

Then, type python3 to open the Python interpreter.

$ python3
Python 3.12.3 (v3.12.3:f6650f9ad7, Apr  9 2024, 08:18:47) 
 [Clang 13.0.0 (clang-1300.0.29.30)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> 

You can exit the Python interpreter by typing either exit() or Ctrl-D plus Return.

Python Interactive Mode

From the command line, type either python on Windows or python3 on macOS to bring up the Python Interpreter, also known as Python Interactive mode. The new prompt of >>> indicates that you are now inside Python itself and not the command line. If you try any previous shell commands we ran--cd, ls, mkdir--they will raise errors. What will work is actual Python code. For example, try out both 1 + 1 and print("Hello Python!"). Press the Enter or Return keys after each command to run them.

>>> 1 + 1
2
>>> print("Hello Python!")
Hello Python!

Python's interactive mode is a great way to save time if you want to try out a short bit of code. However, it has several limitations: You can't save your work in a file, and writing longer code snippets is cumbersome. As a result, we will spend most of our time writing Python and Django in files using a text editor.

To exit Python from the command line, type either exit() and the Enter key or use Ctrl + z on Windows or Ctrl + d on macOS.

Virtual Environments

Installing the latest versions of Python and Django is the correct approach for any new project. However, in the real world, it is common for existing projects to rely on older versions of each. Consider the following situation: Project A uses Django 4.0, but Project B uses Django 5.0. By default, Python and Django are installed globally on a computer: installing and reinstalling different versions every time you want to switch between projects is quite a pain.

Fortunately, there is a straightforward solution. Virtual environments allow you to create and manage separate environments for each Python project on the same computer. You should use a dedicated virtual environment for each new Python and Django project.

There are several ways to implement virtual environments, but the simplest is with the venv module already installed as part of the Python 3 standard library. To try it out, navigate to your desktop's existing ch1-setup directory.

# Windows
$ cd onedrive\desktop\code\ch1-setup

# macOS
$ cd ~/desktop/code/ch1-setup

To create a virtual environment within this new directory, use the format python -m venv <name_of_env> on Windows or python3 -m venv <name_of_env> on macOS. The -m part of this command is known as a flag, which is a convention to indicate the user is requesting non-default behavior. The format is usually - and then a letter or combination of letters. The -m flag is necessary since venv is a module name. It is up to the developer to choose a proper environment name, but a common choice is to call it .venv, as we do here.

# Windows
$ python -m venv .venv

# macOS
$ python3 -m venv .venv

On Windows, the command ls will display the .venv directory in our directory, but it will appear empty on macOS. The .venv directory is there; it's just that it is "hidden" due to the period, ., that precedes the name. Hidden files and directories are a way for developers to indicate that the contents are important and should be treated differently than regular files. To view it, try ls -la, which shows all directories and files, even hidden ones.

$ ls -la
total 0
drwxr-xr-x  3 wsv  staff   96 Dec  12 11:10 .
drwxr-xr-x  3 wsv  staff   96 Dec  12 11:10 ..
drwxr-xr-x  6 wsv  staff  192 Dec  12 11:10 .venv

You will see that .venv is there and can be accessed via cd if desired. The directory also contains a copy of the Python interpreter and a few management scripts, but you will not need to use them directly in this book.

Once created, a virtual environment must be activated. On Windows, there is a one-time additional step of setting an Execution Policy to enable running scripts. The Execution Policy tells Windows, I know what I'm doing here! The Python docs recommend allowing scripts for the CurrentUser only, which is what we will do. On macOS, there are no similar restrictions on scripts, so it is possible to run source .venv/bin/activate directly.

Here is what the complete commands look like to create and activate a new virtual environment called .venv:

# Windows
$ python -m venv .venv
$ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
$ .venv\Scripts\Activate.ps1
(.venv) $

# macOS
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $

The shell prompt now has the environment name (.venv) prefixed, which indicates that the virtual environment is active. Any future changes to Python packages (such as updating existing ones or installing new ones) will occur only within our active virtual environment.

To deactivate and leave a virtual environment, type deactivate.

(.venv) $ deactivate
$

The shell prompt no longer has the virtual environment name prefixed, which means the session is now back to normal.

PyPI (Python Package Index)

PyPI (Python Package Index) is the central location for all Python projects. You can see Django is there along with every other Python package we will use in this book.

We will use pip, the most popular package installer, to install Python packages. It already comes included with Python 3, but to ensure we are on the latest version of pip, let's take a moment to update it. Here is the command to run:

$ python -m pip install --upgrade pip

This command will install and upgrade (if needed) the latest version of pip. Notice that we are not in a virtual environment, so this version of pip will be installed globally on our local computer.

Why do we use python -m pip instead of just pip for this command? The latter does work, but it can cause some issues. Using python with the -m flag ensures that the intended version of Python is in use, even if you have multiple versions of Python installed on your computer. For example, if you have Python 3.7 and 3.12 installed on your computer, it is possible for pip install to use Python 3.7 at one point but Python 3.12 later: not desired behavior. Brett Cannon has a much fuller explanation if you are curious about the underlying reasons why this is the case.

Install Django

Now that we have learned how to install Python properly, use virtual environments, and update pip to the latest version, it is time to install Django for the first time.

In the ch1-setup directory, reactivate the existing virtual environment and install Django.

# Windows
$ .venv\Scripts\Activate.ps1
(.venv) $ python -m pip install django~=5.0.0

# macOS
$ source .venv/bin/activate
(.venv) $ python3 -m pip install django~=5.0.0

This command uses the comparison operator, ~=, to install the latest version of Django 5.0.x. As I type these words, the newest version is 5.0.4, but soon it will be 5.0.5 and then a month later 5.0.6. By using ~=5.0.0, we ensure that the latest version of 5.0.x will be installed when the user executes the command.

If we did not "pin" our version number in this way--if we just installed Django using the command python -m pip install django--then the latest version of Django will be installed. There is no guarantee that all the code in this book will work perfectly on a later version of Django. By specifying the version number for each software package installed, you can update them one at a time to ensure compatibility.

Note: If they differ, I will provide separate Windows and macOS commands. However, when using python on Windows vs. python3 on macOS, the default will be python for conciseness.

First Django Project

To create a new Django project, use the command django-admin startproject django_project .. A Django project can have almost any name, but we will use django_project in this book.

(.venv) $ django-admin startproject django_project .

It's worth pausing here to explain why you should add a period (.) to the end of the previous command. If you just run django-admin startproject django_project without a period at the end, then by default, Django will create this directory structure:

django_project/
 ├── django_project
 │   ├── __init__.py
 │   ├── asgi.py
 │   ├── settings.py
 │   ├── urls.py
 │   └── wsgi.py
 ├── manage.py

Do you see the multiple django_project directories? First, there is a top-level django_project directory, and within it another one containing the files we need for our Django project. Opinions differ on the "best" approach within the Django community, but having these two directories with the same name feels redundant. Deployment is also somewhat simpler with only one django_project directory, so I prefer adding a period to the end that installs Django in the current directory.

├── django_project
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── manage.py

As you progress in your journey learning Django, you will encounter more situations like this, where the Django community has different opinions on the correct best practices. Django is eminently customizable, which is a great strength; however, the tradeoff is that this flexibility comes at the cost of seeming complexity. Generally speaking, it's a good idea to research any such issues, decide, and stick with them!

The Development Server

Django includes a built-in, lightweight local development web server accessible via the runserver command. The development server automatically reloads Python code for each request and serves static files. However, some actions, such as adding files, will not automatically trigger a restart, so if your code is not working as expected, a manual restart is always a good first step.

By default, the server runs on port 8000 on the IP address 127.0.0.1, which is known as the "loopback address" because no data is sent from our computer (host) to the local network or internet; instead, it is "looped back" on itself so the computer sending the data becomes the recipient.

Let's confirm everything is working correctly by starting the local development server now. We'll use manage.py to execute the runserver management command.

(.venv) $ python manage.py runserver
Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).

You have 18 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.
June 28, 2024 - 16:43:31
Django version 5.0.6, using settings 'django_project.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CTRL-BREAK.

Don't worry about the text in red about 18 unapplied migrations. We'll get to that in the next chapter. The critical part, for now, is to visit http://127.0.0.1:8000/ in your web browser and make sure the following image is visible:

Note: On Windows, the final line says to use CONTROL-BREAK to quit, whereas, on macOS, it is CONTROL-C. Newer Windows keyboards often do not have a Pause/Break key, so using the c key usually works.

For readers new to web development, it is worth mentioning that localhost is a common shorthand for 127.0.0.1, so the URL addresses http://127.0.0.1:8000/ and http://localhost:8000/ are functionally equivalent. In this book, we will default to 127.0.0.1:8000 because that is what Django outputs in the terminal, but either option is acceptable.

If you look at your files and folders, you will notice a new db.sqlite3 file has been created. SQLite automatically creates a new file the first time you try to connect if one doesn't already exist.

├── django_project
│   ├── __init__.py
|   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── db.sqlite3  # new
├── manage.py

Go ahead and stop the local server with Control + c. Then, exit the virtual environment by typing deactivate and then Return.

# Windows or macOS
(.venv) $ deactivate

This book provides lots of practice with virtual environments, so don't worry if they are still confusing. The basic pattern for any new Django project is to create and activate a virtual environment, install Django, and then run startproject.

It's worth noting that only one virtual environment can be active in a command-line tab. In future chapters, we will create a new virtual environment for each new project, so either make sure to deactivate your current environment or open a new tab for new projects.

Text Editors

The command line is where we execute commands for our programs, but a text editor is where code is written. The computer doesn't care what text editor you use--the result is just code--but a good text editor can provide helpful hints and catch typos for you.

Many modern text editors are available, and they come with helpful extensions to make Python and Django development more accessible. Two of the more popular options are PyCharm and Visual Studio Code. PyCharm has a paid Professional and free Community version, while VSCode is free. Ultimately, it does not matter what text editor you choose: the result is just code.

VSCode Configurations

If you're not already using a text editor, download and install VSCode from the official website. There are three recommended configurations you can add to improve your developer productivity.

The first is to add the official Python extension to VSCode. On Windows, navigate to File -> Settings -> Extensions; on macOS, Code -> Settings -> Extensions to launch a search bar for the extensions marketplace. Enter "python" and the official Microsoft extension will be the first result. Install it.

The second is adding Black, a Python code formatter quickly becoming the default within the Python community. In the terminal, run the command python -m pip install black on Windows or python3 -m pip install black on macOS.

(.venv) $ python -m pip install black 

Next, within VSCode, open the settings by navigating to File -> Preferences -> Settings on Windows or Code -> Preferences -> Settings on macOS. Search for "default formatter". Under "Editor: Default Formatter" select "Black Formatter" from the drop down list.

Then search for "format on save" and enable "Editor: Format on Save." Black will automatically format your code whenever a *.py file is saved.

To confirm this is working, use your text editor to create and save a new file called hello.py within the ch1-setup directory located on your desktop and type in the following using single quotes:

print('Hello, World!')

On save, it should update automatically to using double quotes, which is Black's default preference: print("Hello, World!"). That means everything is working correctly.

The third and final configuration allows you to open VSCode directly from your terminal. This technique is useful since a standard workflow opens the terminal, navigates to the code directory you want to work on, and opens it with your text editor.

To enable this functionality, press Command + Shift + P simultaneously within VSCode to open the command palette, which allows us to customize our VS Code settings. Then, in the command palette, type shell: the top result will be "Shell Command: Install code command in PATH." Then, hit enter to install this shortcut. A success message will appear: "Shell command 'code' successfully installed in PATH." The PATH variable, by the way, is often used to customize terminal prompts.

Return to your terminal and navigate to the ch1-setup directory. If you type code . it will open up in VS Code.

(.venv) $ code .

Install Git

The final step is to install Git, a version control system indispensable to modern software development. With Git, you can collaborate with other developers, track all your work via commits, and revert to any previous code version, even if you accidentally delete something important! This is not a book on Git, so all necessary commands are given and briefly explained, but there are numerous resources available for free on the internet if you'd like to learn more about Git itself.

On Windows, navigate to the official website at https://git-scm.com/ and click on the "Download" link, which should install the proper version for your computer. Save the file, open your Downloads folder, and double-click on the file to launch the Git for Windows installer. Click the "Next" button through most early defaults, as they are sufficient and can be updated later. Make sure that under "Choosing the default editor used by Git," the selection is for "Use Visual Studio Codeas Git's default editor." In the section on "Adjusting the name of the initial branch in new repositories," make sure the option to "Override the default branch name for new repositories" is selected so that "main" is used.

To confirm that Git is installed on Windows, close all current shell windows and open a new one to load the changes to our PATH variable. (PATH is an environment variable that specifies where executable programs are located. In other words, when you type git, where does your command line look?) Type in git --version to display the installed version of Git.

# Windows
$ git --version
git version 2.45.2.windows.1

On macOS, Xcode is primarily designed for building iOS apps but includes many developer features needed on macOS. Currently, installing Git via Xcode is the easiest option. To check if Git is installed on your computer, type git --version in a new terminal window.

# macOS
$ git --version
git version 2.45.2

If you do not have Git installed, a popup message will ask if you want to install it as part of "command line developer tools." Select "Install," which will load Xcode and its command-line tools package. If you do not see the message, type xcode-select --install instead to install Xcode directly.

Be aware that Xcode is a large package, so the initial download may take some time. Xcode is primarily designed for building iOS apps but includes many developer features needed on macOS. Once the download is complete, close all existing terminal shells, open a new window, and type in git --version to confirm the installation worked.

# macOS
$ git --version
git version 2.45.2

Once Git installs on your local machine, we must do a one-time system configuration by declaring the name and email address associated with all your Git commits. We will also set the default branch name to main. Within the command line shell, type the following two lines. Make sure to update them with your name and email address, not the defaults of "Your Name" and "[email protected]"!

$ git config --global user.name "Your Name"
$ git config --global user.email "[email protected]"
$ git config --global init.defaultBranch main

You can always change these configs later by retyping the same commands with a new name or email address.

Conclusion

Configuring a software development environment from scratch is challenging. Even experienced programmers have difficulty with the task, but it is a one-time pain that is more than worth it. We can now start new Django projects quickly and have learned about the command line, Python interactive mode, how to install the latest version of Python and Django, configured our text editor, and installed Git. Everything is ready for our first proper Django website in the next chapter.