Django is the most popular web development framework for the Python programming language. Its design offers rapid development while keeping to the standards of professionally built applications. It is free, open source, uses the Model-View-Template architectural pattern. Django also includes boilerplates that help developers churn out web apps quickly.

In this tutorial, you will learn and demonstrate how to create a deployment pipeline to continuously deploy your Django apps to a hosting environment.


To follow this tutorial, you will need:

  1. Basic knowledge of the Python programming language
  2. Python (version >= 3) installed on your system and updated
  3. A Heroku account
  4. A CircleCI account
  5. A GitHub account

With all these installed and set up, you can begin the tutorial.

Cloning and running the sample Django project

To get started, you will be cloning a simple Django project you can use for the deployment demonstration. To clone the project, run:

git clone --single-branch --branch base-project

Go to the project root (cd cd-django-app) and run:

python runserver

This command creates a virtual environment, activates the environment, and starts up the project with the local Python server.

Once the virtual environment is created, you can install the dependencies using this command:

#create a venv
python3 -m venv venv

# activate venv
source venv/bin/activate

# install dependencies
pip install -r requirements.txt

# run the server
python runserver

This will boot up the server and run the application at the address http://localhost:8000. Load this address in your browser.

Site run - local

Creating a Heroku app

Next, you need to set up a Heroku application to host the application. Go to your Heroku dashboard and click New -> Create new app. Enter a name for the new application.

New app - Heroku

Make a note of the name you just entered; you will need it later on in the tutorial. Find your Heroku API key in the Account Settings section of your dashboard. You will need this later too.

Automating the deployment of the Django app

Now you can set up the Django project for deployment on Heroku.

Begin by installing the Gunicorn web server for Python. Gunicorn is Heroku’s preferred server for running Django apps in production. At the root of the project, install Gunicorn by running:

pip install gunicorn

Next, install psycopg2, which is the Postgres adapter for Python applications. Enter this command:

pip install psycopg2-binary

For a successful deployment, Heroku also requires the django-heroku package to be installed and configured. Install this package by running:

pip install django-heroku

When the installation is complete, import this latest package at the top of the my_django_project/ file. Place it just below the line from pathlib import Path.

import django_heroku

Then at the bottom of the file, add the following line:


With all dependencies installed, update the requirements.txt file that tracks all dependencies. Enter this command:

pip freeze > requirements.txt

In this command, pip freeze is used to get all the dependencies into the project and send the output of this command into the requirements.txt file. This step is required by Heroku.

Heroku apps include a Procfile that specifies the commands that are executed by the app on startup.

Create a file named Procfile at the root of the project. Add the following line:

web: gunicorn my_django_project.wsgi

This command instructs Heroku to run the application using the gunicorn server. You now have everything in place to make sure that the Django application is successfully deployed to Heroku.

Now you can write the continuous deployment pipeline script that will ship the project from your local environment to Heroku’s remote hosting environment.

At the root of your project, create a folder named .circleci with a file named config.yml inside it. In config.yml, enter this code:

version: "2.1"
  heroku: circleci/heroku@2.0
    executor: heroku/default
      - checkout
      - heroku/install
      - heroku/deploy-via-git
      - deploy

In this configuration, the Heroku orb circleci/heroku@2.0 is imported, which automatically gives access to a set of Heroku jobs and commands that enable ease-of-use of the Heroku toolbelt. One of these jobs is the heroku/deploy-via-git, which deploys your application straight from your GitHub repo to your Heroku account. This job already takes care of installing the Heroku CLI, installing project dependencies, and deploying the application. It also picks up your environment variables to facilitate a smooth deployment to Heroku.

Next, set up a repository on GitHub and link the project to CircleCI. Review pushing your project to GitHub for instructions.

Now, log into your CircleCI account. If you signed up with your GitHub account, all your repositories will be available on your project’s dashboard.

Click Set Up Project next to your cd-django-app project.

You will be prompted to enter the name of the branch your configuration file is on.

Select config

Click Set Up Project. This will trigger your first workflow, which will fail.

CircleCI build failed

The deployment process fails because you have not provided your Heroku API key. To fix that, click the Project Settings button, then click the Environment Variables menu option.

Add two new variables:

  • For HEROKU_APP_NAME, add the app name you used in Heroku. The name will be either cd-django-app or a custom name (if you created one).
  • For HEROKU_API_KEY, enter the Heroku API key that you saved earlier from the account settings page.

Re-run your workflow from the start, and this time your workflow will run successfully.

Build successful - CircleCI

Click to review the details of the deployment.

Build details - CircleCI

The status details are logged to show how Heroku detects the app as a Go application, installs dependencies, builds the project, and runs the command in our Procfile file.

Getting that successful build is great, but you need to confirm that your app actually works error-free on Heroku. To do that, visit your Heroku-assigned application URL. The URL should be in the format https://[APP_NAME] For this tutorial, the URL is:

Site live - Heroku



Python developers love working with Django because of its feature-rich nature and easy-to-use API. Python itself is a developer-friendly language and Django makes using Python for web apps a great choice.

If your team makes use of these tools, let them know about what you have learned in this tutorial. The many benefits of using a continuous deployment pipeline to automatically deploy your Django applications only increase when other team members have access to the information. Make deployments to Heroku one less thing for your team to worry about.

Happy coding!

Fikayo Adepoju is a LinkedIn Learning ( Author, Full-stack developer, technical writer, and tech content creator proficient in Web and Mobile technologies and DevOps with over 10 years experience developing scalable distributed applications. With over 40 articles written for CircleCI, Twilio, Auth0, and The New Stack blogs, and also on his personal Medium page, he loves to share his knowledge to as many developers as would benefit from it. You can also check out his video courses on Udemy.

Read more posts by Fikayo Adepoju