---
id: django-query-builder
version: "4.0.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# django-query-builder — Build complex nested queries

License: permissive · Maintenance: active · Downloads: 231.0K/mo

## What it is and what it does

django-query-builder is a Django library that lets you construct and execute SQL queries programmatically, filling gaps where Django's ORM and .raw() fall short. It's designed for developers who need to build queries dynamically—where the structure itself changes based on runtime conditions—rather than writing static raw SQL strings. The library mirrors SQL syntax closely in its API, so function calls map directly to SQL keywords, making the query construction process more transparent than Django querysets but requiring more SQL familiarity than the ORM.

The package sits between Django's high-level querysets (simple, safe, but limited) and raw SQL strings (flexible but not dynamic). It requires Django 5.2–6.0, Python 3.10–3.14, and Postgres 14+, and depends only on Django itself. It's actively maintained, has no known security vulnerabilities, and carries a permissive MIT license.

Use it for:

- Build upsert (insert-or-update) operations that Django's ORM doesn't natively support
- Construct WHERE clauses, JOINs, or GROUP BY logic dynamically based on user input or application state
- Execute complex nested queries or subqueries that would be awkward to express in Django querysets
- Perform batch database operations with custom logic
- Generate reports or analytics queries with conditional aggregations

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Builds and executes complex SQL queries dynamically in Django applications for database operations that Django's ORM doesn't handle well.

Yes, if you work with Django and Postgres and regularly hit the limits of Django's ORM for complex or dynamic queries. The low install friction, active maintenance, permissive license, and zero known vulnerabilities make it a safe choice. Not necessary if your queries fit comfortably within Django querysets or if you're not using Postgres.

## Install

pip install django-query-builder
uv add django-query-builder
poetry add django-query-builder

## Installing django-query-builder

Before you install: Low friction install with a single Django dependency. Active maintenance as of 2026-07-07, last commit recent. Supports modern Python versions (3.10–3.14) and current Django releases (5.2–6.0).

License in practice: MIT license (permissive) places no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart:

pip install django-query-builder

from django_query_builder import QueryBuilder

qb = QueryBuilder().select('*').from_('users').where('age > 21')
results = qb.execute()

Requires Postgres 14+; Django 5.2–6.0; Python 3.10–3.14. Not compatible with other database backends.

Verify before relying:

- Scope of SQL operations supported beyond upsert (e.g., window functions, CTEs, complex joins)
- Performance characteristics on large result sets or deeply nested queries
- Postgres-only limitation: whether other databases are supported despite the requirement listing
- Specific example usage patterns and API surface for dynamic query construction

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 231.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

django dynamic sql query builder, complex nested sql queries django, raw sql query construction, postgres upsert django, advanced database operations django, sql query generation library, django custom sql builder, django-orm-alternative, postgres-native, dynamic-queries

[View on SkillFed](https://skillfed.io/packages/django-query-builder) · [View on PyPI](https://pypi.org/project/django-query-builder/)