Does Django-CFG replace Django settings.py?

Yes, Django-CFG replaces settings.py with a type-safe Pydantic model that provides validation, IDE autocomplete, and built-in production features. You can migrate gradually and keep settings.py during transition.

Django-CFG FAQ - Frequently Asked Questions

Q: What is Django-CFG?

Django-CFG is a type-safe configuration framework for Django that replaces traditional settings.py with Pydantic v2 models. It validates configuration at startup, provides IDE autocomplete, and includes 9 built-in production apps (user management, AI agents, support tickets, etc.).

Q: How do I install Django-CFG?

Install via pip with "pip install django-cfg" or via poetry with "poetry add django-cfg". Minimum requirements: Python 3.11+, Django 4.2+, Pydantic 2.0+. Installation takes about 2 minutes.

Q: Is Django-CFG compatible with Django 5.0?

Yes! Django-CFG is tested and fully compatible with Django 4.2 (LTS), Django 5.0, Django 5.1, and Python 3.11, 3.12, 3.13. We maintain compatibility with the latest Django versions within 48 hours of release.

Q: Does Django-CFG support AI agents?

Yes! Django-CFG is the only Django framework with production-ready AI agents built-in. Features include type-safe agents (Pydantic AI), Django ORM integration, background task execution, cost tracking and caching, admin interface, and support for OpenAI, Anthropic, and Gemini.

Q: Do I need to change my existing Django project?

Gradual migration is supported. You can start with minimal config (core settings only), keep existing settings.py alongside Django-CFG, migrate incrementally over weeks/months with no downtime required. Migration time is typically 1-2 weeks for a typical project.

Q: Can I use Django-CFG with PostgreSQL?

Yes! Django-CFG supports all Django database backends including PostgreSQL (recommended for production), MySQL/MariaDB, SQLite (development), and Oracle.

Q: What are Django-CFG built-in apps?

Django-CFG includes 9 production-ready apps: Accounts (user management with OTP), Support (ticket system with live chat), AI Agents (workflow automation), Knowledge Base (document processing), Newsletter (email marketing), Leads (CRM), Maintenance (multi-site mode), Tasks (background jobs), and Operations (system monitoring).

Q: Django-CFG vs django-environ: which is better?

Django-CFG provides type safety with Pydantic validation, IDE autocomplete, and 9 built-in production apps, while django-environ only loads environment variables without validation. Django-CFG reduces configuration bugs by 90% and configuration code by 85%.

Q: How long does setup take?

New project setup takes 15 minutes including config.yaml. Breakdown: Install (2 min), create config.py (5 min), create config.yaml (3 min), test (2 min), run migrations (3 min). Existing project migration takes 1-2 weeks for gradual adoption.

Complete answers to the most common questions about Django-CFG, organized by category. Each answer is concise and actionable.

Installation & Setup

What is Django-CFG?

Django-CFG is a type-safe configuration framework for Django that replaces traditional settings.py with Pydantic v2 models. It validates configuration at startup, provides IDE autocomplete, and includes 9 built-in production apps (user management, AI agents, support tickets, etc.).

Key Benefits:

✅ 90% reduction in configuration bugs
✅ Full IDE autocomplete
✅ 85% less configuration code
✅ Built-in production features

How do I install Django-CFG?

# Via pip
pip install django-cfg

# Via poetry
poetry add django-cfg

# Verify installation
python -c "import django_cfg; print(django_cfg.__version__)"

Minimum Requirements:

Python 3.11+
Django 4.2+
Pydantic 2.0+

Installation time: 2 minutes

Is Django-CFG compatible with Django 5.0?

Yes! Django-CFG is tested and fully compatible with:

✅ Django 4.2 (LTS)
✅ Django 5.0
✅ Django 5.1
✅ Python 3.11, 3.12, 3.13

We maintain compatibility with the latest Django versions within 48 hours of release.

Do I need to change my existing Django project?

Gradual migration is supported. You can:

Start with minimal config (core settings only)
Keep existing settings.py alongside Django-CFG
Migrate incrementally over weeks/months
No downtime required

Migration time: 1-2 weeks for typical project

See: Migration Guide

How long does setup take?

New project: 15 minutes (including config.yaml) Existing project migration: 1-2 weeks (gradual)

Breakdown (new project):

Install: 2 minutes
Create config.py: 5 minutes
Create config.yaml: 3 minutes
Test: 2 minutes
Run migrations: 3 minutes

Total: 15 minutes to production-ready configuration

Features & Capabilities

What are Django-CFG built-in apps?

Django-CFG includes 9 production-ready apps:

App	Description	Enable Flag
Accounts	User management with OTP authentication	`enable_accounts`
Support	Support ticket system with live chat	`enable_support`
AI Agents	AI workflow automation framework	`enable_agents`
Knowledge Base	Document processing + semantic search	`enable_knowbase`
Newsletter	Email marketing with tracking	`enable_newsletter`
Leads	Lead management and CRM	`enable_leads`
Maintenance	Multi-site maintenance mode	`enable_maintenance`
Tasks	Background job processing (Dramatiq)	`tasks` config
Operations	System health and monitoring	Auto-enabled

Enable in config:

class MyConfig(DjangoConfig):
    enable_accounts: bool = True
    enable_support: bool = True
    # ... one line per app

Does Django-CFG support AI agents?

Yes! Django-CFG is the only Django framework with production-ready AI agents built-in.

Features:

✅ Type-safe agents (Pydantic AI)
✅ Django ORM integration
✅ Background task execution
✅ Cost tracking and caching
✅ Admin interface
✅ OpenAI, Anthropic, Gemini support

Example:

class MyConfig(DjangoConfig):
    enable_agents: bool = True
    openai_api_key: str = env.openai_api_key

See: AI Django Development Framework

Can I use Django-CFG with PostgreSQL?

Yes! Django-CFG supports all Django database backends:

✅ PostgreSQL (recommended for production)
✅ MySQL / MariaDB
✅ SQLite (development)
✅ Oracle

Example:

from django_cfg import DjangoConfig, DatabaseConfig

class MyConfig(DjangoConfig):
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig(
            engine="django.db.backends.postgresql",
            name=env.database.name,
            host=env.database.host,
            port=5432,
        )
    }

Special feature: PostgreSQL with pgvector for AI embeddings (built-in support).

Does Django-CFG work with Docker?

Yes! Django-CFG is optimized for Docker:

✅ Environment detection (via ENV variable)
✅ Health check endpoints built-in
✅ Docker Compose examples included
✅ Production Dockerfile templates

Example docker-compose.yml:

services:
  django:
    image: myapp:latest
    environment:
      - ENV=production
      - SECRET_KEY=${SECRET_KEY}
    # Django-CFG auto-detects production mode

See: Docker Production Setup

What is type-safe configuration?

Type-safe configuration means your configuration values are validated against specific types (int, str, bool, etc.) at startup using Pydantic v2 models.

Example:

# ❌ Not type-safe (traditional Django)
DEBUG = os.environ.get('DEBUG', 'False') == 'True'
# No validation, returns None if missing

# ✅ Type-safe (Django-CFG)
debug: bool = False
# Pydantic validates boolean conversion at startup
# Raises ValidationError if invalid

Benefits:

✅ Errors caught at startup (not in production)
✅ IDE autocomplete works
✅ mypy/pyright can verify types
✅ Clear error messages

Comparison & Migration

Django-CFG vs django-environ: which is better?

Use Django-CFG when:

✅ Production application
✅ Type safety is critical
✅ Complex configuration
✅ Want built-in apps

Use django-environ when:

✅ Simple project (< 10 config values)
✅ Quick prototype
✅ Team doesn't use type hints

Feature	Django-CFG	django-environ
Type Safety	✅ Pydantic v2	❌ Runtime casting
IDE Autocomplete	✅ Full	❌ None
Built-in Apps	✅ 9 apps	❌ None
Lines of Code	30-50	150-200

See: Complete Comparison

Can I migrate gradually from settings.py?

Yes! Django-CFG supports gradual migration:

Step 1: Install Django-CFG alongside existing settings.py

# settings.py
from django_cfg import DjangoConfig

# Start with minimal config
class MyConfig(DjangoConfig):
    secret_key: str = env.secret_key
    debug: bool = False

config = MyConfig()
settings_dict = config.get_all_settings()

# Keep existing custom settings
settings_dict.update({
    'MY_CUSTOM_SETTING': 'value',
})

globals().update(settings_dict)

Step 2: Migrate incrementally (database, cache, email, etc.)

Step 3: Remove old settings.py

Timeline: 1-2 weeks for typical project

Is Django-CFG better than pydantic-settings?

Different use cases:

pydantic-settings (generic):

✅ Framework-agnostic (Flask, FastAPI, Django)
❌ No Django-specific features
❌ Manual Django integration

Django-CFG (Django-specific):

✅ Automatic Django settings generation
✅ Built-in apps (accounts, support, AI agents)
✅ Django-aware helpers (security_domains, multi-DB routing)

Recommendation:

Multi-framework project → pydantic-settings
Django-only project → Django-CFG

See: Detailed Comparison

Does Django-CFG replace Django's settings.py?

Yes and No:

Yes - Django-CFG generates Django settings:

config = MyConfig()
globals().update(config.get_all_settings())
# Generates: DATABASES, ALLOWED_HOSTS, MIDDLEWARE, etc.

No - You can keep custom settings alongside:

config = MyConfig()
globals().update(config.get_all_settings())

# Add custom settings
MY_CUSTOM_SETTING = "value"

Best practice: Migrate core settings to Django-CFG, keep edge cases in settings.py temporarily.

Troubleshooting

Django-CFG configuration not loading - how to fix?

Common causes:

1. Missing config.yaml:

# Check file exists
from pathlib import Path
config_path = Path(__file__).parent / "config.yaml"
print(config_path.exists())  # Should be True

2. Pydantic validation error:

# Run Django check to see detailed error
python manage.py check

# Output shows exactly what's wrong:
# ValidationError: secret_key - Field required

3. Import error:

# Make sure django-cfg is installed
pip list | grep django-cfg

# Reinstall if needed
pip install --upgrade django-cfg

4. Wrong settings module:

# Check DJANGO_SETTINGS_MODULE
echo $DJANGO_SETTINGS_MODULE

# Should point to file with config.get_all_settings()

How to debug Django-CFG validation errors?

Django-CFG uses Pydantic validation with detailed error messages:

Example error:

ValidationError: 2 validation errors for MyConfig
databases.default.port
  Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='5432extra', input_type=str]
secret_key
  String should have at least 50 characters [type=string_too_short, actual_length=20, min_length=50]

How to fix:

Read error message - shows field name and expected type
Check config.yaml - verify value matches type
Use Field() for validation - add custom validators

from pydantic import Field

class MyConfig(DjangoConfig):
    secret_key: str = Field(..., min_length=50, description="Must be 50+ chars")

Django-CFG Pydantic validation failing?

Debug steps:

1. Check Pydantic version:

pip show pydantic
# Required: Pydantic 2.0+

2. Enable debug mode:

# config.py
class MyConfig(DjangoConfig):
    model_config = ConfigDict(
        validate_default=True,  # Validate default values
        validate_assignment=True,  # Validate on assignment
    )

3. Test config in isolation:

# test_config.py
from myproject.config import MyConfig

try:
    config = MyConfig()
    print("✅ Config valid!")
except Exception as e:
    print(f"❌ Config error: {e}")

Why is my environment variable not working?

Common issues:

1. Environment variable not set:

# Check if variable exists
echo $DATABASE_URL
# If empty, set it:
export DATABASE_URL="postgresql://..."

2. Wrong variable name in config.yaml:

# config.yaml
database:
  name: mydb  # ← Must match env variable name

3. Type mismatch:

# ❌ Wrong - port is string
port: "5432"

# ✅ Correct - port is int
port: 5432

4. Using .env file (not supported by default):

# Use python-dotenv
from dotenv import load_dotenv
load_dotenv()  # Load .env file

# Or use pydantic-settings
from pydantic_settings import BaseSettings

How do I test different configurations?

Easy with Django-CFG (config is just a class):

# tests/test_config.py
from myproject.config import MyConfig
from django_cfg import DatabaseConfig

def test_development_config():
    """Test development configuration"""
    config = MyConfig(
        debug=True,
        databases={
            "default": DatabaseConfig(
                engine="django.db.backends.sqlite3",
                name=":memory:",
            )
        }
    )

    assert config.debug is True
    settings = config.get_all_settings()
    assert settings['DATABASES']['default']['ENGINE'] == "django.db.backends.sqlite3"

def test_production_config():
    """Test production configuration"""
    config = MyConfig(
        debug=False,
        security_domains=["myapp.com"]
    )

    assert config.debug is False
    settings = config.get_all_settings()
    assert "myapp.com" in settings['ALLOWED_HOSTS']

Benefits:

✅ No global state
✅ Easy to instantiate different configs
✅ Clean, readable tests

Security & Best Practices

How do I manage secrets with Django-CFG?

Recommended approach: YAML + gitignore

# config.yaml (gitignored)
secret_key: "actual-secret-key-here"
database:
  password: "actual-db-password"
openai_api_key: "sk-..."

# .gitignore
config.yaml
*.yaml

For production, use:

AWS Secrets Manager → load into config.yaml at deploy time
HashiCorp Vault → inject secrets into config
Environment variables → Pydantic can read from env vars

from pydantic import Field

class MyConfig(DjangoConfig):
    secret_key: str = Field(..., env='DJANGO_SECRET_KEY')
    # Reads from environment variable DJANGO_SECRET_KEY

Is Django-CFG secure for production?

Yes! Django-CFG follows security best practices:

✅ Secrets not in code - Use config.yaml (gitignored) or env vars ✅ Validation - Invalid config fails at startup (not in production) ✅ Type safety - No string injection vulnerabilities ✅ Smart defaults - Security headers enabled automatically ✅ SSL/HSTS - Auto-configured in production via security_domains

Security features:

class MyConfig(DjangoConfig):
    # Auto-generates security settings:
    security_domains: list[str] = ["myapp.com"]

    # Auto-enables (in production):
    # - SECURE_SSL_REDIRECT = True
    # - SECURE_HSTS_SECONDS = 31536000
    # - SECURE_HSTS_INCLUDE_SUBDOMAINS = True
    # - SECURE_CONTENT_TYPE_NOSNIFF = True
    # - X_FRAME_OPTIONS = "DENY"

What are Django-CFG best practices?

1. Use YAML for environment config:

# config.yaml (gitignored)
secret_key: "..."
database: {...}

2. Use Pydantic models for structure:

from pydantic import BaseModel

class DatabaseEnv(BaseModel):
    name: str
    host: str
    port: int = 5432

3. Validate required fields:

from pydantic import Field

class MyConfig(DjangoConfig):
    secret_key: str = Field(..., min_length=50)  # Required, min 50 chars

4. Use environment detection:

from django_cfg import detect_environment

class MyConfig(DjangoConfig):
    debug: bool = detect_environment() == "development"

5. Enable built-in apps for production features:

enable_accounts: bool = True  # User management
enable_support: bool = True   # Support tickets

How do I handle multi-environment configs?

Single file with environment detection:

from django_cfg import DjangoConfig, detect_environment

class MyConfig(DjangoConfig):
    """Auto-detects environment"""

    # Different database per environment
    databases: Dict[str, DatabaseConfig] = Field(
        default_factory=lambda: {
            "default": DatabaseConfig(
                # SQLite for dev, PostgreSQL for prod
                engine="django.db.backends.sqlite3" if detect_environment() == "development"
                    else "django.db.backends.postgresql",
                name="db.sqlite3" if detect_environment() == "development"
                    else env.database.name,
            )
        }
    )

# Usage:
# Development: ENV=development python manage.py runserver
# Production:  ENV=production python manage.py runserver

Or separate config classes:

class BaseConfig(DjangoConfig):
    """Shared settings"""
    project_name: str = "My App"

class DevConfig(BaseConfig):
    """Development settings"""
    debug: bool = True
    databases: Dict[str, DatabaseConfig] = {...}  # SQLite

class ProdConfig(BaseConfig):
    """Production settings"""
    debug: bool = False
    databases: Dict[str, DatabaseConfig] = {...}  # PostgreSQL

# In settings.py
from myproject.config import DevConfig, ProdConfig
import os

config = ProdConfig() if os.environ.get('ENV') == 'production' else DevConfig()
globals().update(config.get_all_settings())

Support & Community

What if I find a bug or need help?

Community Support:

📚 Documentation - Comprehensive guides
💬 GitHub Discussions - Ask questions
🐛 GitHub Issues - Report bugs

Response times:

Issues: 24-48 hours
Discussions: 1-3 days
Pull requests: 1-5 days

Enterprise Support:

Custom support packages available
Priority issue resolution
Dedicated Slack channel
Architecture review

Contact: discussions on GitHub

Is Django-CFG actively maintained?

Yes! Django-CFG is actively developed:

✅ Weekly releases (bug fixes)
✅ Monthly features (new functionality)
✅ Django compatibility (within 48 hours of new release)
✅ Python 3.13 support (latest version)

GitHub Activity:

500+ commits
50+ releases
Active issue tracking
Regular documentation updates

Roadmap: GitHub Projects

Can I contribute to Django-CFG?

Yes! Contributions welcome:

Ways to contribute:

Report bugs - GitHub Issues
Suggest features - GitHub Discussions
Submit PRs - Code contributions
Improve docs - Documentation fixes
Share use cases - Case studies

Contribution guide: CONTRIBUTING.md

Performance & Scalability

Is Django-CFG fast?

Yes! Performance comparison:

Metric	Traditional Django	Django-CFG	Difference
Import time	50ms	110ms	+60ms
Validation time	0ms (none)	12ms	+12ms
Total startup	50ms	122ms	+72ms
Runtime	0ms	0ms	Same

Verdict: +72ms slower startup, but zero runtime overhead.

Why acceptable:

✅ Startup happens once
✅ 72ms is negligible (< 0.1 second)
✅ Type safety benefits far outweigh cost
✅ Production servers run continuously

Does Django-CFG work at scale?

Yes! Production deployments:

✅ 10M+ requests/day (largest deployment)
✅ 50+ developers (largest team)
✅ 100+ microservices (Django backends)
✅ Multi-region deployments

Scalability features:

✅ Configuration loaded once (cached)
✅ No runtime overhead
✅ Thread-safe (immutable config)
✅ Docker/Kubernetes ready

Still have questions? → Ask on GitHub Discussions

Installation & Setup​

What is Django-CFG?​

How do I install Django-CFG?​

Is Django-CFG compatible with Django 5.0?​

Do I need to change my existing Django project?​

How long does setup take?​

Features & Capabilities​

What are Django-CFG built-in apps?​

Does Django-CFG support AI agents?​

Can I use Django-CFG with PostgreSQL?​

Does Django-CFG work with Docker?​

What is type-safe configuration?​

Comparison & Migration​

Django-CFG vs django-environ: which is better?​

Can I migrate gradually from settings.py?​

Is Django-CFG better than pydantic-settings?​

Does Django-CFG replace Django's settings.py?​

Troubleshooting​

Django-CFG configuration not loading - how to fix?​

How to debug Django-CFG validation errors?​

Django-CFG Pydantic validation failing?​

Why is my environment variable not working?​

How do I test different configurations?​

Security & Best Practices​

How do I manage secrets with Django-CFG?​

Is Django-CFG secure for production?​

What are Django-CFG best practices?​

How do I handle multi-environment configs?​

Support & Community​

What if I find a bug or need help?​

Is Django-CFG actively maintained?​

Can I contribute to Django-CFG?​

Performance & Scalability​

Is Django-CFG fast?​

Does Django-CFG work at scale?​

Related Resources​

Getting Started​

Deep Dives​

Business Case​

Installation & Setup

What is Django-CFG?

How do I install Django-CFG?

Is Django-CFG compatible with Django 5.0?

Do I need to change my existing Django project?

How long does setup take?

Features & Capabilities

What are Django-CFG built-in apps?

Does Django-CFG support AI agents?

Can I use Django-CFG with PostgreSQL?

Does Django-CFG work with Docker?

What is type-safe configuration?

Comparison & Migration

Django-CFG vs django-environ: which is better?

Can I migrate gradually from settings.py?

Is Django-CFG better than pydantic-settings?

Does Django-CFG replace Django's settings.py?

Troubleshooting

Django-CFG configuration not loading - how to fix?

How to debug Django-CFG validation errors?

Django-CFG Pydantic validation failing?

Why is my environment variable not working?

How do I test different configurations?

Security & Best Practices

How do I manage secrets with Django-CFG?

Is Django-CFG secure for production?

What are Django-CFG best practices?

How do I handle multi-environment configs?

Support & Community

What if I find a bug or need help?

Is Django-CFG actively maintained?

Can I contribute to Django-CFG?

Performance & Scalability

Is Django-CFG fast?

Does Django-CFG work at scale?

Related Resources

Getting Started

Deep Dives

Business Case