How to setup Postgres locally for Django on Mac

The easiest way to have local instance of PostgreSQL on your macOS system available for your Django projects.

Published: Dec. 30, 2020
App Store

With Django I would say it is pretty common to have SQLite as a developer database and then on the server have Postgres as "the real" production database. While this setup is pretty easy (you get configuration for SQLite out of the box) it has some issues.

You can get yourself into a situation where your app works locally but does not start on the server, because there is a small difference in how these two databases work. For example SQLite does not care about length of the text in columns.

In my case, what kind of forced me to have local PostgreSQL for one of my projects, was search. Postgres offers powerful full-text search you can use from Django. So developing this feature without Postgres database would be kind of crazy.

Anyway, let's see how to setup Postgres locally.

We will start with the Postgres part that is not Django specific. There are more than one ways how to install this database on your machine, however downloading is the easiest. This also assumes you don't have other versions of Postgres installed.

You can get the dmg file from the official site. The most up to date version is " with PostgreSQL 13" as of writing this post in December 2020. Download it, open and move the to Applications folder on your Mac.

Now all that is left to do is to run the app. Click the "Start" button and your server is ready to go.


The Django part

If you already deployed your app on the server with Postgres, you probably installed the psycopg2 package to talk to the database.

However this won't work on your local machine. Because this package for the setup expects to find standard Postgres installation on your machine. While you can configure PATH for this to work, there is easier solution.

Install the binary version like this:

pip install psycopg2-binary

And done.


If you haven't made any changes, you can use the default settings for Django.

    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'NAME': 'your_username',
        'USER': 'your_username',
        'PASSWORD': '',
        'HOST': 'localhost',
        'PORT': '5432',

You just need to substitute your_username for the username you are using on your Mac.

And with this done, Postgres is ready to go.

I am using this "trick" to switch databases in one of my projects:

from sys import platform

IS_MAC_MACHINE = platform == "darwin"

It is not super ideal but I am reasonably confident that this app will never be deployed to Mac based sever..

I would like to offer advice regarding Windows and Linux but unfortunately I don't have any direct experience so it is best to try another source. Maybe the official docs on the download page will be enough.

Filip Němeček profile photo


Filip Němeček

iOS blogger and developer with interest in Python/Django. Want to see most recent projects? 👀

iOS blogger and developer with interest in Python/Django. Want to see most recent projects? 👀