GitHubEmailContact
Skip to main content

Installation Guide

Quick Start

Get a production-ready Django project in 30 seconds with the CLI: django-cfg create-project "My Project"

Installation Process Overview​

Requirements​

Python Version

Python 3.12+ is required. Django-CFG uses modern Python features and type hints.

Django must be installed separately (peer dependency). Compatible with Django 4.2+ and Django 5.x.

Quick Installation​

1. Install Django-CFG​

# Create virtual environment
python3.12 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install Django and Django-CFG
pip install django
pip install django-cfg
Virtual Environment

Always use a virtual environment to avoid dependency conflicts. Never install Django-CFG globally.

2. Create Project with CLI​

# Create complete project structure
django-cfg create-project "My Project"

# Navigate to project
cd my-project

# Run development server
python manage.py runserver
What Gets Created

The CLI creates a complete production-ready project with:

  • Type-safe configuration with pydantic-settings
  • Environment variable configuration (.env files)
  • Modern admin interface (Unfold)
  • API documentation (DRF Spectacular)
  • All migrations and initial data :::

Access your application:

Alternative Installation Methods​

Using different package managers
# Create project directory
mkdir my-project && cd my-project

# Initialize Poetry
poetry init --no-interaction

# Add dependencies
poetry add django django-cfg

# Create project structure
poetry run django-cfg create-project "My Project"

Using pipenv​

# Create environment and install
pipenv install django django-cfg

# Create project
pipenv run django-cfg create-project "My Project"

Using uv (Fast)​

# Create environment
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install django django-cfg

# Create project
django-cfg create-project "My Project"

Manual Project Setup​

If you prefer manual setup instead of create-project CLI:

1. Install Django​

pip install django

2. Create Django Project​

django-admin startproject myproject
cd myproject

3. Install Django-CFG​

pip install django-cfg

4. Create Environment Module​

Create myproject/environment/ directory:

myproject/
├── myproject/
│   ├── __init__.py
│   ├── environment/           # New directory
│   │   ├── __init__.py
│   │   ├── loader.py
│   │   ├── config.dev.yaml
│   │   ├── config.prod.yaml
│   │   └── config.test.yaml
│   ├── config.py              # New file
│   └── settings.py
└── manage.py
environment/__init__.py
from .loader import env

__all__ = ["env"]
Configuration Guide

See Configuration Guide for complete loader.py implementation with Pydantic models.

5. Create Configuration Class​

myproject/config.py
from django_cfg import DjangoConfig, DatabaseConfig
from typing import Dict
from .environment import env


class MyProjectConfig(DjangoConfig):
    """Project configuration loaded from YAML"""

    # From environment YAML
    secret_key: str = env.secret_key
    debug: bool = env.debug

    project_name: str = env.app.name
    site_url: str = env.app.site_url
    api_url: str = env.app.api_url

    # Security
    security_domains: list[str] = env.security_domains or []

    # Database from URL
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig.from_url(url=env.database.url)
    }


# Create instance
config = MyProjectConfig()

6. Update settings.py​

Replace settings.py content with:

settings.py
from .config import config

# Import all Django-CFG settings
globals().update(config.get_all_settings())

# Optional: add custom Django settings
STATIC_URL = '/static/'
MEDIA_URL = '/media/'
Settings Order

Always import config.get_all_settings() first, then add custom settings. This ensures proper override behavior.

7. Run Django​

python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Optional Features​

Django-CFG supports optional feature groups (extras) for specific use cases. Install only what you need:

pip install django-cfg[full]

Includes: All optional dependencies (grpc, centrifugo, rq, ai, and more)

Use case: Full-featured production setup with all integrations

Combine Multiple Extras

You can install multiple extras at once:

pip install django-cfg[grpc,centrifugo,rq]
# or with Poetry
poetry add django-cfg[grpc,centrifugo,rq]

Troubleshooting​

Python Version Error​

# Using Homebrew
brew install python@3.12

# Verify installation
python3.12 --version

Virtual Environment Not Activating​

# Check available Python versions
ls /usr/bin/python*
ls /usr/local/bin/python*

# Try full path
/usr/local/bin/python3.12 -m venv .venv

# Or use virtualenv
pip install virtualenv
virtualenv -p python3.12 .venv

Django Not Installed​

Peer Dependency

Django is a peer dependency and is not installed automatically with django-cfg. You must install it separately.

pip install django

Compatible versions:

  • Django 4.2+ ✅
  • Django 5.0+ ✅
  • Django 5.1+ ✅

Dependencies​

Django-CFG automatically installs:

Core Dependencies

Type Validation & Configuration:

  • pydantic >=2.11.0 - Type validation
  • pydantic-settings >=2.0.0 - Environment configuration
  • python-dotenv >=1.0.0 - .env file loading
  • click >=8.2.0 - CLI interface

Django Integration:

  • djangorestframework >=3.16.0
  • djangorestframework-simplejwt >=5.5.0
  • django-cors-headers >=4.7.0
  • django-redis >=6.0.0
  • django-unfold >=0.64.0 - Modern admin

Database:

  • psycopg >=3.2.0 - PostgreSQL driver
  • dj-database-url >=3.0.0 - Database URL parsing

See pyproject.toml for complete dependency list.

Verification​

Verify installation:

# In Python shell
import django_cfg
print(django_cfg.__version__)  # Should print version

from django_cfg import DjangoConfig
# Should not raise ImportError

Next Steps​

Start Building​

Explore Features​

Configuration Deep Dive​

Migration​

Troubleshooting​

  • Troubleshooting - Common installation and configuration issues
  • FAQ - Frequently asked questions

TAGS: installation, setup, pip, poetry, django-cfg DEPENDS_ON: [intro] USED_BY: [configuration, first-project]

Last updated on