Django is the most popular web development framework for the Python programming language. Its design facilitates rapid development without compromising on the standards of professionally built applications. It is free, open source, uses the Model-View-Template architectural pattern, and encapsulates a lot of boilerplates to enable 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 post, a few things are required:

  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

Once cloned, go into the project root (cd cd-django-site) and run the following command to start up the project with the local Python 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

Your next step is 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 this later on in the tutorial. Next, locate your Heroku API key in the Account Settings section of your dashboard. You will also need this later in the tutorial.

Account Settings - Heroku

Setting up a CircleCI project for deployment

To begin this process, you first need to push the project to a remote repository on GitHub. Make sure that this is the GitHub account connected to your CircleCI account.

Next, go to the Projects page (click Projects on the vertical menu on the right) on the CircleCI dashboard. Add the project.

Add Project - CircleCI

Click Set Up Project to begin. Click Skip this step on the modal that pops up. We will be manually adding our CircleCI config later in this tutorial.

Add Config - CircleCI

On the Setup page, click Use Existing Config to indicate that you are adding a configuration file manually and not using the sample displayed. Next, you get a prompt to either download a configuration file for the pipeline or start building.

Build Prompt - CircleCI

Click Start Building. This build will fail because we have not set up our configuration file yet.

The final thing we need to do on the CircleCI console is to set up environment variables for the project we just added. This will enable our project to have authenticated access to our Heroku application for deployments.

Go to your project’s settings by clicking the Project Settings button on the Pipelines page. Make sure your project is the one that is selected.

Project settings - CircleCI

Back on the Project Settings page, click Environment Variables on the side menu.

On the Environment Variables page, click Add Environment Variable.

Add Environment variable - CircleCI

Add the following environment variables:

  • HEROKU_APP_NAME is the name of your Heroku application (in this case the name is cci-cd-django).
  • HEROKU_API_KEY is your Heroku account API key. You can copy and paste it from Heroku’s account page.

Now that you have added environment variables, you have everything set up on your CircleCI console for deployment to Heroku.

Automating the deployment of the Django app

To finalize the process, you will need to 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 the command above, 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.

Next, create a file named Procfile at the root of the project (Heroku apps include a Procfile that specifies the commands that are executed by the app on startup) and 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@0.0.10
      - heroku/deploy-via-git

In this configuration, the Heroku orb circleci/heroku@0.0.10 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.

Commit all changes to the project and push to your remote GitHub repository. This will automatically trigger the deployment pipeline.

Build Successful - CircleCI

Success! Next, click the build (heroku/deploy-via-git), for details about the deployment.

Build Details - CircleCI

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