Python Development Workflow

Before following this guide, be sure you have a Terminal and Editor as described in our prerequisites. We will also refer to some git commands from Git Workflow, however you can skip those if you’re not using git at this time.

Step 1: Install Python

macOSWindowsLinux

• Go to python.org and select “Downloads”.

• Click the Download button.

• Install the downloaded file in the usual way.

Step 2: Create a project directory

Creating a dedicated directory (commonly called a folder) is a good starting point. This is often called your project folder, project directory, project dir, or project root.

We recommend storing all of your code in central directory, called “Source”, within your home directory. In this guide, we’ll refer to ~/Source/. We’ll also refer to your project as myproject.

If you’re working on a project with a git repo, start by cloning that repo:

macOSWindowsLinux

% cd ~/Source
% git clone <myproject-url>

If you’re starting a new project, create a new directory and initialize an empty git repo.

macOSWindowsLinux

% cd ~/Source
% mkdir myproject
% cd myproject
% git init .

Step 3: Create a virtual environment

Python projects require installing additional 3rd-party packages, such as Django. However, this creates a problem — what if two different projects need two different versions of a package? You’d then have to uninstall and reinstall every time you switched between the projects, which could cause a lot of problems.

Python includes a solution: “virtual environments”, referred to as venv. A venv is simply a folder which contains a separate copy of Python and all the installed packages. This way, each project won’t interfere with any others on your machine.

Let’s create a venv in a folder named “.venv”. The dot at the beginning implies that this is a hidden folder. Open the Terminal, navigate to your project, and run:

macOSWindowsLinux

% cd ~/Source/myproject
% python3 -m venv .venv

Step 4: Activate your venv

You’ll need to do this every time you work on your project. Activating a venv simply means you’re switching your terminal over to using the specific Python environment for your project.

macOSWindowsLinux

% cd ~/Source/myproject
% source .venv/bin/activate

Following this, you’ll see your terminal prompt now show a (.venv) at the beginning. This is how you know that you’re currently using the venv.

Step 5: Manage pip packages

pip is the tool used to install packages, such as Django or Wagtail. Before using pip, always make sure your venv is activated following Step 4 above.

To install packages, it is necessary to keep a list of all the packages required by this project. The file containing this list is named requirements.txt. If you’re working on a new project, go ahead and create or edit the requirements.txt file in your project directory. In this example, let’s install Django version 5.1.

# Inside the requirements.txt file.
django==5.1.*

Here’s an explanation of what the special syntax means:

• django is the name of the package.

• == means to install a version equal to…

• 5.1.* means any version matching 5.1. Django frequently releases security patches, such as 5.1.1, 5.1.2, 5.1.3, etc. These patches are guaranteed to be backwards compatible, so you usually want the latest to automatically be installed, hence the *.

Follow this same process for every package you need.

Now that you have a requirements.txt, install it as so:

macOSWindowsLinux

(.venv) % pip install -r requirements.txt

Step 6: Improve quality with developer tools

“Linters”, which are tools that check your code for errors, can drastically help improve the quality of your code, and are essential for producing professional software.

Since these tools are only used by humans writing code, and are not used in the production web server, we will separate them into a requirements-dev.txt file, as so:

# Inside requirements-dev.txt file.

# First, install project requirements.
-r requirements.txt

# Now, install developer tools.
ruff

In this file, we are first installing everything from the main requirements.txt, then installing one additional tool: ruff. Ruff can format your Python code and also check for errors.

Now, let’s install, then run ruff:

macOSWindowsLinux

(.venv) % pip install -r requirements-dev.txt
(.venv) % ruff check --fix
(.venv) % ruff format

You might see that ruff reformatted your code, or is telling you to fix some errors. Run this every time you make changes to your code.

Step 7: Django & Wagtail specific instructions

At this point, your Python environment is all set up and working. However, Django & Wagtail projects usually need a MySQL or PostgreSQL database. To get that working in your development environment, need to follow one of these guides:

• Set Up a Local MySQL Database

• Set Up a Local PostgreSQL Database

Finally, every time you make a change to a model in your Django or Wagtail project, you should be sure to create and run migrations. Migrations synchronize those changes in your Django models with your database.

macOSWindowsLinux

(.venv) % python manage.py makemigrations
(.venv) % python manage.py migrate

Step 8: Git commit

If you’re using git, you’ll want to follow our Git Workflow. However, this is your reminder to commit and push any changes before logging off for the day!

Note

Never commit your .venv folder to git. This is because it is specific to your machine, and won’t work on other people’s machines. It is also very large and will slow down your git repository.

If running git status shows files from the .venv folder, then you’ll want to create or edit a file named .gitignore in your project directory. Copy the contents of this file into your .gitignore: https://www.toptal.com/developers/gitignore/api/django.