heroku/python-getting-started: a barebones Django app with two deploy paths

A Django project with one job, not a library

heroku/python-getting-started is a Django project with a single purpose: give a new Python developer something they can push to Heroku without assembling the deployment themselves. The README describes it as "A barebones Django app, which can easily be deployed to Heroku", and that framing sets the scope of everything else here. It supports the tutorials for both the Cedar and Fir generations of the platform, and the repository homepage points at the Dev Center article "Getting Started on Heroku with Python" as the companion walkthrough. The topic list holds django, heroku, heroku-languages, python and sample-app, which reads as a sample rather than a library. There is no published package, no importable API, and no released version to install. Nobody adds this to a requirements file of their own. What you get is a deploy path plus the minimum runtime scaffolding a Django app needs to boot on a Heroku dyno, so the intended reader is someone following a tutorial who wants a working target at the end of it.

The platform split, and what it forces on the commands

Heroku documents two platform generations, and this repository keeps one tutorial path for each. Cedar is the older generation and Fir is the newer one. The difference shows up in three concrete places. On Cedar, the README notes that apps default to Eco dynos if you are subscribed to Eco, and to Basic dynos otherwise, then points at a post about the low-cost plans for the reasoning. On Fir, apps default to 1X-Classic dynos, and you cannot create an app there until you have created a private space, which is precisely why the Fir command line differs. Third, the Fir sequence includes a wait step that the Cedar sequence does not. So this is not one sample with two spellings of the same instructions. It is the same code base whose deployment steps had to diverge when the platform diverged, and keeping both sets in one README is a reasonable response to that split rather than an accident.

Cedar: clone, create, push, open

The Cedar path assumes you already have the Heroku CLI installed and authenticated. The sequence is short enough to read in a single pass, and it is the whole tutorial in practice. Clone the repository, move into the directory, let the CLI create the app, push the main branch to it, and open the result in a browser.

$ git clone https://github.com/heroku/python-getting-started
$ cd python-getting-started
$ heroku create
$ git push heroku main
$ heroku open

Worth being precise about what the second and third lines do, because the README does not spell it out. The create command provisions the app on the platform and registers it as a git remote under the name heroku, which is what makes the next line work without any remote setup of your own. The push then sends the current main branch to that remote, and Heroku builds and runs it on a dyno. If the clone URL differs because you forked it, or your branch is not named main, those are the only two lines you need to touch. The documentation also links to the CLI page for destroying an app and to a separate page about removing the Postgres add-on, both of which matter more than the deployment itself. No environment variables are set anywhere in this sequence, even though a .env file sits at the top level with contents that are not shown.

Fir adds a space and a wait that Cedar never needs

The Fir path differs in two lines rather than in two ideas. Because a private space has to exist before an app can be created there, the create call takes a space argument, and the documentation says to create that space first. The wait step then sits between the push and the open, so the browser opens an app that is already up rather than one that might still be starting.

$ git clone https://github.com/heroku/python-getting-started
$ cd python-getting-started
$ heroku create --space <space-name>
$ git push heroku main
$ heroku ps:wait
$ heroku open

The space name is a placeholder you must replace with a space you created yourself, and the wait command is the one instruction in this repository with no Cedar counterpart at all.

ps:wait is a black box in this repository

That wait command is the least documented thing in the whole project. Neither the README nor the visible files explain what ps:wait polls, how long it waits before giving up, or what output it produces while it runs. If it hangs on a failed build, you are reading Heroku's own documentation, not this repository. The space argument has the same problem in milder form, since the placeholder cannot be copied literally and still succeed. Treat both lines as pointers to platform documentation rather than as self-explanatory steps, and budget time for that detour if you are teaching this walkthrough to someone new to the platform. A related gap sits on the Cedar side: nothing in the documented sequence tells you how to confirm the build succeeded before you open the browser, so the open command becomes your de facto health check.

Four pinned dependencies and a database driver that is switched off

The dependency list is short, and every entry carries a narrow version range, which pins the sample to a known set of releases without pinning exact patch versions.

django>=6.1,<6.2
gunicorn>=26,<27
dj-database-url>=3,<4
whitenoise>=6,<7

# Uncomment to use a Postgres database.
#psycopg[binary]

The Postgres driver line is present but commented out, with a note that uncommenting it enables a Postgres database, so a fresh clone installs no database driver at all. That single commented line tells you the default experience of this app is a deployment without persistence.

The file tree explains the runtime without documenting it

Look at the top level and the runtime becomes legible without opening a single file. A Procfile and a Procfile.windows sit at the root, which is where Heroku reads its process declarations from, and the two filenames suggest the Windows variant is maintained alongside the Unix one. gunicorn.conf.py tells you that Gunicorn is the serving layer in front of Django, and manage.py is the usual Django management entry point. Two Python packages, gettingstarted/ and hello/, hold the application code. project.toml is present at the root as well, though its keys are not visible here, and dj-database-url appears in the dependency list next to a .env file at the top level, which suggests the database connection is configured through the environment rather than a hardcoded settings file. The documentation does not describe any of these files individually, so the tree gives you the shape and you fill in the contents from the Dev Center articles. app.json sits in the same category: present, unexplained, and easy to mistake for configuration you are meant to edit.

Idle dynos bill you, and there is no release to pin

Using resources for this example app counts towards your usage, and the documentation asks you to delete both the app and the database as soon as you are done experimenting, in order to control costs. The Cedar path makes that easy to forget, because a forgotten app simply sits there on Basic or Eco dynos until you remember. The same page mentions a Heroku for GitHub Students program through which eligible students can apply for platform credits, which softens the cost for that group. On the maintenance side, the repository is not archived and the last push was on 2026-10-20, so the sample is current with the platform rather than abandoned. It publishes no GitHub releases, though, which means there is no version to pin, no changelog, and nothing to upgrade to. The license is the Unlicense, a public domain dedication, so there are no reuse or attribution conditions to track when you copy the code into your own project. That last point is the real reason to treat this as a starting template rather than a dependency: copy it, rename it, own it.

Editorial conclusion

Adopt this repository if your next task is a Heroku tutorial run and you want a target that boots in five commands. It suits a workshop and suits a production service poorly. Skip it if you need authentication, a real settings module, a database driver enabled out of the box, or a versioned release to pin, since the repository ships no releases and leaves the Postgres driver commented out. Before you build on it, check the two things the documentation leaves open: what heroku ps:wait polls and how long it waits, and what the Procfile and project.toml files declare, since neither file's contents are shown. Also confirm the dyno plan, and delete both the app and the add-on when you finish, because the resource usage is billed to your account from the moment it runs.

Frequently asked questions

Official sources

1. heroku/python-getting-started on GitHub
2. Issues
3. License: Unlicense
4. Project website
5. README