Chapter 1: Initial Setup
Course Contents
- Changelog
- Foreword
- Introduction
- Chapter 1: Initial Setup
- Chapter 2: Hello, World Website
- Chapter 3: Personal Website
- Chapter 4: Company Website
- Chapter 5: Message Board Website
- Chapter 6: Blog Website
- Chapter 7: Blog Forms
- Chapter 8: Blog User Accounts
- Chapter 9: Newspaper Project
- Chapter 10: Newspaper User Authentication
- Chapter 11: Newspaper Style with Bootstrap
- Chapter 12: Newspaper Password Change and Reset
- Chapter 13: Newspaper Articles App
- Chapter 14: Newspaper Permissions and Authorization
- Chapter 15: Newspaper Comments
- Chapter 16: Performance
- Chapter 17: Deployment
- Chapter 18: Web APIs
- Conclusion
This chapter focuses on configuring your Windows or macOS computer to work on Django projects. You are probably eager to dive in and start using Django, but configuring your computer now for Django development is a one-time task that will pay dividends later. You will become comfortable with the command line and shell commands, learn how to use virtual environments, install Python 3.14, choose 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 most computer users are familiar with. Regular computer users will never need to use the command line. Still, for software developers, it is a vital, regularly used tool for executing programs, installing software, using Git for version control, and connecting to cloud servers. With practice, most developers find the command line a faster, more powerful way to navigate and control a computer.
With its minimal user interface—just a blank screen and a blinking cursor—the command line can feel 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 pasting 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 you type and run commands. These terms can be confusing at first, but they essentially mean the same thing: the command line is where we run text-only commands on our computer.
On Windows, you'll use a terminal application to access a shell that runs your commands. The terminal is the window; the shell is the program inside it that interprets what you type. On Windows 11, the default terminal is Windows Terminal and the default shell is PowerShell. On Windows 10, both are typically combined into a single app called Windows PowerShell. Either way, you'll get the same working command line for the purposes of this book.
To open it, click the taskbar next to the Windows button at the bottom of the screen and type "PowerShell"—this works on both Windows 10 and 11—then launch the result. You'll see a new window with a dark background and a blinking cursor after the > prompt.
PS C:\Users\wsv>
The PS before the path indicates PowerShell. After it comes the current location in the file system: the C: drive, the Users directory, and my user directory wsv within it. 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. Going forward, we'll use the shorter > prompt for Windows.
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.
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
Many shell commands are available, but developers generally rely on a handful for day-to-day use and look up more complex 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 Enter key. Note that the # symbol represents a comment not executed on the command line.
# Windows
$ whoami
wsv2026\wsv
# macOS
$ whoami
wsv
You can save your Django code anywhere, but we will place it in your home directory, the folder that holds your personal files such as Documents and Downloads. Both systems use the ~ symbol as a shortcut, and the command cd (change directory) followed by the intended location works on both.
# Windows or macOS
$ cd ~
Why not the desktop, which may seem more convenient? On many Windows computers, OneDrive moves the desktop to a different location and continuously syncs everything on it to the cloud. That breaks the file paths used in this book, and syncing the thousands of files a Django project's virtual environment contains is slow and can cause strange errors. The home directory avoids both problems on every computer.
Tip: The Tab key will autocomplete a command, so if you type cd Doc and then hit Tab, the rest of the name, Documents, will be filled in automatically.
To create a new directory, use the command mkdir followed by the name. We will create a code directory in the home directory, then create a new directory named ch1-setup within it.
# Windows or macOS
$ mkdir code
$ cd code
$ mkdir ch1-setup
$ cd 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 key autocompletes the line. The ↑ and ↓ keys cycle through previous commands, saving you from typing the same thing over and over again.
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, the recommended way to install and manage Python is the Python Install Manager (often shortened to "PyManager"), a small standalone tool published by the Python Software Foundation. It replaces the older approach of downloading a standalone .exe installer for each Python version, which is being phased out and will not be produced for Python 3.16 or later.
PyManager is hosted on the Microsoft Store. In the search bar at the bottom of your screen, type "python" and select the result for "Python Install Manager". Click the blue "Get" button to download it. If the Microsoft Store isn't available on your computer, as is sometimes the case on work or school machines, you can instead download the installer from the Python downloads page and double-click the file to install it.
Once the install manager is in place, open a new PowerShell window and use the py command to install Python 3.14:
$ py install 3.14
PyManager also wires up a global python command that points to your latest installed version, which is why the verification step below uses python rather than py.
To confirm everything is working, check the version:
$ python --version
Python 3.14.4
The py command itself is also useful: py list shows every Python version installed on your system, and py -3.14 launches a specific version explicitly. This is especially useful when you have multiple Python versions installed for different projects.
Then, type python to open the Python interpreter from the command-line shell.
$ python
Python 3.14.4 (tags/v3.14.4:23116f9, Apr 7 2026, 14:10:54)
[MSC v.1944 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>
You can exit the Python interpreter by typing exit(). As a shortcut, press Ctrl + Z and then Enter on Windows, or Ctrl + D on macOS.
Install Python 3 on macOS
On macOS, the official installer on the Python website is the best approach. In a new browser window, go to the Python downloads page and find the latest Python 3.14 release in the list of releases (at the time of writing, 3.14.4). This book uses Python 3.14, so don't click the main "Download" button if it offers a newer version such as 3.15. On that release page, click "Download macOS installer." 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.14.4
Then, type python3 to open the Python interpreter.
$ python3
Python 3.14.4 (v3.14.4:23116f998f6, Apr 7 2026, 09:45:22)
[Clang 17.0.0 (clang-1700.6.4.2)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>
Exit the Python interpreter by pressing Ctrl + D or typing exit() before continuing on to the next section.
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, mkdir, whoami—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 key 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. Make sure to exit the Python interpreter before continuing on.
Virtual Environments
Installing the latest versions of Python and Django is the correct approach for any new project. However, in the real world, existing projects often rely on older versions of each. Consider the following situation: Project A uses Django 6.0, but Project B uses Django 6.1. By default, Python and Django are installed globally on a computer, so installing and reinstalling different versions every time you switch between projects is 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.
You can implement virtual environments in several ways, but the simplest is the venv module, which comes standard with Python 3. uv is a fast Rust-based alternative, but venv and pip ship with Python on every installation, and the skills transfer directly to any project you encounter. If you decide to switch to uv or another package manager in the future, doing so is relatively straightforward.
To try out these native tools, navigate to the existing ch1-setup directory.
# Windows
$ cd ~\code\ch1-setup
# macOS
$ cd ~/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, a convention indicating the user is requesting non-default behavior. The format is usually a hyphen, followed by a letter or combination of letters. The -m flag is necessary since venv is a module name. Developers can choose any environment name, but a common choice is .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, but it will appear empty on macOS. The .venv directory is there; it's just "hidden" due to the period (.) before the name. The leading dot is a Unix convention for configuration and system files; they're hidden from normal listings to keep things uncluttered, not because they're unimportant. On macOS, try ls -la, which shows all directories and files, even hidden ones.
Note: ls -la is a macOS (and Linux) command. On Windows, PowerShell's ls works differently and doesn't accept -la, but you don't need it: plain ls already shows the .venv directory.
$ 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.
After you create it, you must activate the virtual environment. On macOS, there are no restrictions, so you can run source .venv/bin/activate directly. On Windows, you have one additional step: set an Execution Policy to enable running scripts. The Execution Policy tells Windows, "I know what I'm doing here!" and allows the .venv\Scripts\Activate.ps1 activation script to run. The Python docs recommend allowing scripts only for the CurrentUser, which is what we will do.
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.
Install Django
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 Django. pip comes included with Python 3, so we don't need to install it separately.
In the ch1-setup directory, reactivate the existing virtual environment, upgrade pip to the latest version, and then install Django.
# Windows
$ .venv\Scripts\Activate.ps1
(.venv) $ python -m pip install --upgrade pip
(.venv) $ python -m pip install django~=6.1.0
# macOS
$ source .venv/bin/activate
(.venv) $ python3 -m pip install --upgrade pip
(.venv) $ python3 -m pip install django~=6.1.0
Why do we use python -m pip instead of just pip? The shorter form works, but python and pip are separate commands that don't necessarily point to the same Python installation. If you have Python 3.12 and 3.14 installed on your computer, you could run one but install packages into the other. That's what we want to avoid! The -m flag tells Python to use its own built-in pip, which guarantees the package lands in the Python version you're actually using.
Is it the end of the world if you just use pip install for packages? No. Is it better and safer to use this longer format? Yes.
The Django install command uses the compatible release operator, ~=, to install the latest version of Django in the 6.1.x series. As I type these words, the newest version is 6.1.2, but soon it will be 6.1.3, then 6.1.4, and so on. By specifying ~=6.1.0, we install whatever the latest 6.1.x release is at the time—but never 6.2.0 or higher. That upper bound matters: a later feature release like 6.2 could introduce changes that break the book's code.
If we did not "pin" our version number in this way—if we just ran python -m pip install django—then pip would install the newest version of Django available, whatever that happens to be. There is no guarantee that all the code in this book would work perfectly on a later version. By specifying a version for each package we install, we can upgrade them one at a time and confirm compatibility as we go.
Note: If they differ, I will provide separate Windows and macOS commands. However, when using python on Windows vs. python3 on macOS, I'll use python by default 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, which creates the project 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 best approach. Django is eminently customizable, which is a great strength—but that flexibility can also make the framework seem more complex than it is. Generally, it's a good idea to research the issue, decide, and stick with it.
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 as needed 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 works 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.
October 9, 2026 - 16:40:35
Django version 6.1.2, using settings 'django_project.settings'
Starting WSGI development server at http://127.0.0.1:8000/
Quit the server with CTRL-BREAK.
WARNING: This is a development server. Do not use it in a production setting. Use a production WSGI or ASGI server instead.
For more information on production servers see: https://docs.djangoproject.com/en/6.1/howto/deployment/
Don't worry about the red text 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 macOS, the output says to quit the server with CONTROL-C, whereas on Windows, it says CTRL-BREAK. Newer Windows keyboards often do not have a Pause/Break key, so using Ctrl + C 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 Ctrl + C. Then, exit the virtual environment by typing deactivate and then pressing Enter.
# 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.
Only one virtual environment can be active in a command-line tab. In future chapters, we'll create a new virtual environment for each new project, so either 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 or IDE (Integrated Development Environment) is where we write code. The computer doesn't care what text editor you use—the result is just code—but a good text editor can offer helpful hints and catch typos.
This is a highly personal choice. Popular options include PyCharm, Visual Studio Code, Zed, and many others. (Full disclosure: I work at JetBrains as a Developer Advocate focused on PyCharm.) Resist the temptation to blindly copy a more experienced developer's setup, because it's easy to add an overwhelming number of plugins and shortcuts you don't fully understand.
My advice is to start with a minimal setup, then add tooling only when you understand it and know you need it. Investigating further options such as linters, type checkers, and code formatters is worth the time, but is beyond the scope of this book.
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 Git book, so it gives only the necessary commands and brief explanations.
On Windows, navigate to the official website at https://git-scm.com/ and click on the "Download" link, which should download the proper installer for your computer. Save the file, open your Downloads folder, and double-click on the file to launch the Git for Windows installer. Click "Next" through most of the early defaults—they are sensible and can be updated later.
The one screen worth pausing on is "Adjusting the name of the initial branch in new repositories": select "Override the default branch name for new repositories" 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 your PATH variable. (PATH is an environment variable that tells the command line where to look for executable programs: when you type git, PATH is the list of directories your shell searches to find that program.) Type git --version to display the installed version of Git.
# Windows
$ git --version
git version 2.55.0.windows.1
On macOS, Git ships as part of the Xcode Command Line Tools, a package of developer command-line utilities provided by Apple. (This is not the full Xcode IDE, which is a much larger separate download from the Mac App Store designed primarily for building iOS apps. The Command Line Tools are a smaller, focused package that includes Git and other essentials.) Installing them is currently the easiest way to get Git on macOS.
To check if Git is already installed, type git --version in a new terminal window. If Git is not yet installed, a pop-up message will ask if you want to install it as part of "Command Line Developer Tools." Select "Install" to begin downloading the Command Line Tools. If you do not see the message, type xcode-select --install to trigger it manually. The download may take a few minutes. Once it is complete, close all existing terminal windows, open a new one, and type git --version again to confirm the installation worked.
# macOS
$ git --version
git version 2.55.0
Once Git is installed on your local machine, run a one-time global configuration to set the name and email address associated with your Git commits, and set the default branch name to main. Within the command-line shell, type the following three lines, replacing the placeholder name and email with your own.
$ git config --global user.name "Your Name"
$ git config --global user.email "yourname@email.com"
$ 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.
GitHub
Git tracks changes on your own computer. GitHub is a website that stores a copy of your Git repositories online, serving as a backup and making it easy to share code. Starting in Chapter 3, we will push our projects to it. If you don't already have an account, create a free one now.
GitHub doesn't accept your account password when you push code from the command line, so there is one more one-time step: letting Git sign in on your behalf.
On Windows, you don't need to do anything else. Git for Windows includes a tool called Git Credential Manager: the first time you push code, a browser window opens so you can sign in to GitHub, and your login is saved for next time.
On macOS, the Git that comes with Apple's Command Line Tools can't sign in through a browser. The simplest fix is GitHub's official command-line tool, GitHub CLI. Download the macOS installer from its website, run it, then type:
$ gh auth login
Answer the prompts: choose GitHub.com, then HTTPS, answer Yes when asked to authenticate Git with your GitHub credentials, and choose Login with a web browser. Copy the one-time code it displays, press Enter, and paste the code into the browser page that opens. From now on, git push will work without asking for a password.
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. Along the way, we've learned about the command line and Python's interactive mode, installed the latest versions of Python and Django, and set up Git and GitHub. We can now start new Django projects quickly, and everything is ready for our first proper Django website in the next chapter.