Django on Vercel in 30 minutes

5 min readApr 30, 2021

Zeit Now has become Vercel. It’s still an easy and inexpensive way to get access to serverless compute for a Django app. Here’s how.

This guide will help you get started with Django on Vercel using a custom builder for Python WSGI applications: vercel-python-wsgi. You can see a the result of this guide on GitHub.

The plan

Set up a barebones Django application
Install the Vercel command line tools
Configure the project for Vercel
Deploy!

1. Set up a barebones Django application

For the sake of example, we’ll work with what Django gives us out of the box with just a few small additions.

Start a new Django project

$ mkdir vercel-django-example
$ cd vercel-django-example
$ pip install Django
$ django-admin startproject vercel_app .

This establishes a new Django project in ./vercel-django-example/. I’m skipping over any environment management assuming you have your own preference (check out direnv if you’re in the market).

In setting up your environment, you should be sure to use either Python 3.6 or Python 3.8 as these are the only Python runtimes supported by Vercel.

Add an app to the project

$ python manage.py startapp example

This creates a stubbed application in ./vercel-django-example/example.

Update your project settings to include example in the list of INSTALLED_APPS:

And update your project URLs to include the URLs from the new app:

Add a view and route

Within the example app create a single view and route so that you have a page to load when visiting the site on Vercel.

First, in the example/views.py file that Django created for you with the app, add a simple view:

And add a route to the view in example/urls.py:

Check your progress

With the work so far, your Django app should display your view when visiting the root URL. You can test with the local development server:

$ python manage.py runserver

Step 1 complete! 🎉

Install the Vercel command lines tools

Although it’s possible to use Vercel without using the CLI (e.g., through the GitHub integration) — starting new projects from the command line is by far the easiest to get up and running.

Vercel’s CLI is an NPM package and can be installed readily:

$ yarn add global vercel

Logging in is then as simple as:

$ vercel login

Be sure to register for an account on vercel.com if you don’t already have a login.

Step 2 done! 👍

Configure the project for Vercel

There are three chores to take care of before you’re ready for deployment: adding a Vercel configuration, fixing some settings, and listing our dependencies.

Add a Vercel configuration file

First, add a Vercel configuration file, vercel.json, to the root of your project:

Under "builds", "src": "vercel_app/wsgi." points to the file that contains a WSGI application declaration (Django created it for you).
"use": "@ardnt/vercel-python-wsgi" tells Now to use the @ardnt/vercel-python-wsgi builder. The latest version of the builder will be installed from NPM when you deploy our project during the build step.
"config": { "maxLambdaSize": "15mb" } increases the size limit of our bundle (the default is 5MB) — this may not be necessary, but Django is a large package, so it saves a headache if size becomes an issue. Feel free to experiment with the appropriate upper limit.
"routes": [ ... ] rewrites all routes ("src": "/(.*)") to our WSGI application ("dest": "now_app/wsgi.py") to be handled.

You can see the full documentation for the Vercel configuration file on the docs website.

Notice that we are using configuration features that are marked legacy in the documentation. While this isn’t necessary (you could configure your project for the official Vercel Python runtime), it is preferable since it will enable you to take advantage of multiple builds from a single project (e.g., a second build for static files).

Update your Django settings

Next, you’ll need to adjust two Django project settings.

First, update ALLOWED_HOSTS to allow vercel.app to be a valid hostname for your app.

Second, clear out your settings for DATABASES — this will prevent Django from searching for a database adapter (which is not available given the barebones nature of the Lambda compute environment).

Enumerate dependencies

Finally, you’ll need to list out dependencies in a requirements.txt file so that the builder knows what to install for you before deploying.

That’s it! You’re ready to go! 🍰

Deploy!

A little bit of configuration pays big dividends for your next step. To get a live working version of your app, all you need to do is run:

$ vercel

Follow the prompts, pointing the builder to ./ for your project code.

That’s it! After the build completes, your application will be available.

$ vercel
Vercel CLI 21.3.3
? Set up and deploy “vercel-django-example”? [Y/n] y
...
? In which directory is your code located? ./
...
✅  Production: https://vercel-django-example.vercel.app [copied to clipboard] [29s]

Congratulations!

Why not use the official Python Vercel runtime?

There is a Python builder/runtime maintained by the Vercel team. It’s a very similar implementation and has ASGI support which may be interesting for some projects.

However, there are two issues that limit it’s application and have driven me toward a custom builder:

The Vercel Python runtime/builder is highly opinionated about the file structure of a project — I want to be able to name files and folders in a way that helps myself and other developers, instead of being required to use Vercel’s convention.
ASGI support is interesting, but irrelevant for serverless implementations of Django — Serverless implies 1 request = 1 isolated compute unit. A serverless invocation won’t be handling large volumes of requests. Django is synchronous under the hood, so switching to ASGI doesn’t gain performance on serverless architectures.

Since I don’t need ASGI and would prefer a builder that is agnostic to how I organize the project source, I prefer the vercel-python-wsgi builder over the official runtime.

Now vs. Vercel

This guide is a nearly 1-for-1 replica of the same guide for Now. For the time being, the builder conventions that worked on Now still work on Vercel and this guide will get you up and running quickly.

Check back in the future for revisions to this guide as Vercel matures their new runtime convention and phases out builder support.