SaaS Pegasus Django Boilerplate (Open Source Edition)

The original SaaS boilerplate for Django — trusted by thousands.

A free, open-source, production-grade starting point for your next Django application. Spin up a Django app with a modern front-end stack and built-in essentials in minutes. Optimized for building in the AI-agent era.

This is the open-source edition of SaaS Pegasus, the Django SaaS boilerplate that has powered thousands of startups and products since 2019. It gives you a real, batteries-included foundation to build on, and a taste of the architecture, conventions, and tooling used by SaaS Pegasus projects.

Looking for more? The pro version of SaaS Pegasus adds Stripe subscriptions, teams & multi-tenancy, a host of AI and agent-based capabilities, one-click deployments, and much more. See everything in SaaS Pegasus Pro →

What's included

This boilerplate ships with a complete, modern Django foundation:

• 🐍 Django 6 on Python 3.14 — a clean, well-organized project structure following Django best practices.
• 🔐 Authentication — sign-up, login, password reset, and email verification via django-allauth.
• ⚡ HTMX + Alpine.js — single-page-app interactivity without the single-page-app complexity.
• 🎨 Tailwind CSS v4 + DaisyUI — a modern, themeable component library, integrated with Vite via django-vite.
• 🔌 REST API — built on Django REST Framework with an auto-generated, OpenAPI-typed client.
• 🧵 Background tasks — Celery workers and scheduled jobs, backed by Redis.
• 🐘 Postgres — the standard Django database, ready to go.
• 🐳 Docker — local services (Postgres, Redis) wired up with Docker Compose.
• 🛠️ Tooling — Uv for Python, Vite for front end, Ruff formatting/linting, pre-commit hooks, a test suite, and GitHub Actions CI.
• 🤖 Agent-ready — ships with CLAUDE.md/AGENTS.md and built-in skills files, so coding agents understand how to work with the codebase out of the box.

Custom codebase creator

You can create a free, personalized version of this project using the SaaS Pegasus codebase creator (requires signup). This lets you change project details, add/remove features, and change your preferred coding assistant. You'll also get one-click upgrades and tools for coding agents to configure your project for you.

Don't need customizations? That's fine too, just fork this project and start coding!

Open-source edition vs. SaaS Pegasus Pro

This repo is a great way to start hobby/personal Django projects and evaluate SaaS Pegasus. The pro version is more suitable for business-grade SaaS and AI applications.

Check out SaaS Pegasus Pro →

Quickstart

Prerequisites

To run the app in the recommended configuration, you will need the following installed:

• Docker and Docker Compose
• uv (for Python)
• node and npm (for JavaScript)

On Windows, you will also need to install make, which you can do by following these instructions.

Initial setup

Run the following command to initialize your application:

This will:

• Build and run your Postgres database
• Build and run your Redis database
• Run your database migrations
• Install front end dependencies

Then you can start the app:

This will run your Django server and build and run your front end (JavaScript and CSS) pipeline.

Your app should now be running! You can open it at localhost:8000.

If you're just getting started, try these steps next.

Using the Makefile

You can run make to see other helper functions, and you can view the source of the file in case you need to run any specific commands.

Installation - Native

You can also install/run the app directly on your OS using the instructions below.

You can setup a virtual environment and install dependencies in a single command with:

This will create your virtual environment in the .venv directory of your project root.

Set up database

If you are using Docker you can skip these steps.

Create a database named project.

Create database migrations:

uv run manage.py makemigrations

Create database tables:

Running server

uv run manage.py runserver

Building front-end

To build JavaScript and CSS files, first install npm packages:

Then build (and watch for changes locally):

Running Celery

Celery can be used to run background tasks.

Celery requires Redis as a message broker, so make sure it is installed and running.

You can run it using:

celery -A project worker -l INFO --pool=solo

Or with celery beat (for scheduled tasks):

celery -A project worker -l INFO -B --pool=solo

Note: Using the solo pool is recommended for development but not for production.

Installing Git commit hooks

To install the Git commit hooks run the following:

uv run pre-commit install --install-hooks

Once these are installed they will be run on every commit.

For more information see the docs.

Running Tests

To run tests:

Using make:

Native:

Or to test a specific app/module:

Using make:

make test ARGS='apps.web.tests.test_basic_views --keepdb'

Native:

uv run manage.py test apps.web.tests.test_basic_views --keepdb

On Linux-based systems you can watch for changes using the following:

find . -name '*.py' | entr uv run manage.py test apps.web.tests.test_basic_views

Documentation

This project is built with SaaS Pegasus, and all relevant parts of the Pegasus documentation apply here too.

Splitting out the open-source documentation from the pro documentation is still a work in progress.

Support

This open-source edition is provided as-is, and is supported by the community. Issues and pull requests are welcome.

For dedicated support, priority bug fixes, and the full feature set, check out SaaS Pegasus. There is also a community Slack instance for all Pegasus Pro customers.

License

This boilerplate is released under the MIT License — free to use for personal and commercial projects.