dj-database-url is a simple Django utility that allows you to configure your Django application's database using a single 12-factor inspired `DATABASE_URL` environment variable. It parses the URL and returns a Django-compatible database connection dictionary, supporting various backend types like PostgreSQL, MySQL, SQLite, and Oracle. Currently at version 3.1.2, it is actively maintained by the Jazzband community with regular updates.
Install & Compatibility
Where this runs
tested against v3.1.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.037s · 66.3MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 3.4s · import 0.036s · 67MB
65MB installed
● package 65MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Primary function for configuring from DATABASE_URL environment variable.
from dj_database_url import config
Used to parse a database URL string directly.
from dj_database_url import parse
To quickly set up `dj-database-url` in your Django `settings.py`, use the `config()` function. It reads the `DATABASE_URL` environment variable, falling back to a SQLite default if not present. It's recommended to include `conn_max_age` and `conn_health_checks` for production reliability.
import os
import dj_database_url
# In your Django settings.py
DATABASES = {
'default': dj_database_url.config(
default=os.environ.get('DATABASE_URL', 'sqlite:///db.sqlite3'),
conn_max_age=600,
conn_health_checks=True,
)
}
# Example of how DATABASE_URL might be set in your environment (e.g., .env file or deployment config)
# export DATABASE_URL="postgres://user:password@host:port/dbname"
# export DATABASE_URL="sqlite:///path/to/my/db.sqlite3"
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.