dj-database-url

library3.1.2pypypi✓ verified 26d ago

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.

database web-framework

pip install dj-database-url

github ↗package ↗homepage ↗changelog ↗

INSTALL

IMPORT

SIG · DJ-DATABASE-URL

dj-database-url

databasepythonv3.1.2

Install

3.5s avg

Import

35ms

Disk

66MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.036s · 66.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.5s · import 0.034s · 67MB

66MB installed

● package 66MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

config

✓ from dj_database_url import config

Primary function for configuring from DATABASE_URL environment variable.

parse

✓ from dj_database_url import parse

Used to parse a database URL string directly.

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"

Debug

Known issues

breakingVersion 3.0.0 introduced a new decorator registry pattern for database connection string checks and broke some API compatibility. It also updated supported Python and Django versions.

fix

Review the official documentation for the new registry pattern if you have custom database string implementations or are extending functionality. Ensure your Python and Django versions meet the new requirements (e.g., Python >=3.10, Django >=4.x).

affects: >=3.0.0

breakingVersion 2.3.0 removed support for Python 3.8 and Django 3.

fix

Upgrade your Python environment to 3.9+ (preferably 3.10+) and your Django project to Django 4.0+.

affects: >=2.3.0

gotchaFor performance and reliability in production, it's highly recommended to explicitly set `conn_max_age` (for persistent connections) and `conn_health_checks` (for checking connection validity) when using `dj_database_url.config()`.

fix

Pass `conn_max_age=600` (or another appropriate value) and `conn_health_checks=True` to `dj_database_url.config()`.

affects: All

gotchaWhen connecting to SQLite with an absolute file path, ensure you use four slashes (e.g., `sqlite:////full/path/to/your/database/file.sqlite`). The extra slashes are necessary because the 'file' portion is treated as the database's filename, not a hostname.

fix

Use the `sqlite:////` prefix for absolute file paths, or `sqlite:///./relative/path.sqlite3` for relative paths.

affects: All

gotchaOracle database URLs expect the format `user:password` separated by a colon, not a forward slash as sometimes seen in other Oracle tools. You can also omit `HOST` and `PORT` and provide a full DSN string or TNS name in the `NAME` part of the URL.

fix

Format Oracle URLs with `user:pass@host:port/dbname` or use DSN/TNS in the `NAME` part as per Oracle's connection string specifications, ensuring proper colon separation for user/password.

affects: All

gotcha`dj_database_url.config()` will raise a `UserWarning` if no `DATABASE_URL` environment variable is set and no `default` URL is provided in the function call.

fix

Always provide a `default` argument to `dj_database_url.config()` (e.g., `default='sqlite:///db.sqlite3'`) or ensure the `DATABASE_URL` environment variable is set in your execution environment.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'dj_database_url'

The 'dj-database-url' library has not been installed in the Python environment where Django is running.

fix

Run `pip install dj-database-url` to install the package.

django.core.exceptions.ImproperlyConfigured: settings.DATABASES is improperly configured. Please supply the ENGINE value.

Django's DATABASES setting is being set to an empty dictionary by `dj_database_url.config()` because the `DATABASE_URL` environment variable is not defined, and no default URL was provided.

fix

Ensure the `DATABASE_URL` environment variable is set in your environment or provide a `default` argument to `dj_database_url.config()` in your `settings.py` (e.g., `dj_database_url.config(default='sqlite:///db.sqlite3')`).

django.db.utils.OperationalError: could not connect to server: Connection refused

The Django application, configured by `dj-database-url`, is unable to establish a connection with the database server, often due to an incorrect host or port in the `DATABASE_URL`, firewall restrictions, or the database server not running.

fix

Verify that the `DATABASE_URL` environment variable contains the correct host, port, username, and password. Ensure the database server is running and accessible from where your Django application is deployed, checking for any network or firewall issues.

KeyError: '' (within dj_database_url.py when parsing url.scheme)

`dj-database-url` is attempting to parse a `DATABASE_URL` that is either empty or malformed, resulting in an empty scheme, which commonly occurs during deployment commands like `collectstatic` if the `DATABASE_URL` environment variable is not correctly propagated to the build process.

fix

Ensure the `DATABASE_URL` environment variable is properly set and accessible in the environment where the command is being run, or provide a valid `default` URL to `dj_database_url.config()` (e.g., `DATABASES = {'default': dj_database_url.config(default='sqlite:///:memory:')}`).

Upgrade

Version history

3.1.2latest on PyPI · released Feb 19, 2026

Audit

Dependencies

psycopg2-binaryoptionalRequired for PostgreSQL database connections (optional).

mysqlclientoptionalRequired for MySQL database connections (optional).

cx_OracleoptionalRequired for Oracle database connections (optional).

Agent activity

21 hits · last 30 days

node

Resources

githubhttps://github.com/jazzband/dj-database-url ↗

packagehttps://pypi.org/project/dj-database-url/ ↗

homepagehttps://jazzband.co/projects/dj-database-url ↗

changeloghttps://github.com/jazzband/dj-database-url/blob/master/CHANGELOG.md ↗