---
title: Installation
description: Install Django-CFG and create your first project
sidebar_label: Installation
sidebar_position: 2
keywords:
  - install django-cfg
  - django-cfg setup
  - pip install django-cfg
  - django-cfg optional dependencies
---

# Installation

## Install the Package

```bash
pip install django-cfg
```

Or with optional dependency groups:

```bash
pip install "django-cfg[grpc]"       # gRPC support
pip install "django-cfg[full]"       # All enterprise features
```

## Optional Dependency Groups

| Group | What it adds |
|-------|-------------|
| `grpc` | gRPC server support (grpcio, grpcio-tools) |
| `centrifugo` | Real-time messaging (cent) |
| `rq` | Redis Queue tasks (rq, django-rq) |
| `ai` | Pydantic AI agents |
| `geo` | Geographic/PostGIS support |
| `full` | All enterprise features |

<Callout type="tip">
Start with the base install. You can add optional groups later as your project grows.
</Callout>

---

## Requirements

| Tool | Version | Note |
|------|---------|------|
| Python | 3.12+ | Required |
| Django | 5.0+ | Installed automatically with django-cfg |
| Node.js | 20+ | For frontend (pnpm will be needed) |
| Docker | Latest | Optional — for local services (Redis, PostgreSQL, Centrifugo) |

---

## Create a Project

```bash
django-cfg create-project myproject
cd myproject
```

This generates a project structure with Pydantic v2 configuration, auto-discovered extensions, and sensible defaults.

### Verify Installation

```bash
django-cfg --version
django-cfg info
```

---

## Run the Development Server

<Tabs items={['With Poetry', 'With pip']}>
  <Tabs.Tab>
```bash
cd myproject

# Install Python dependencies
poetry install

# Run migrations
poetry run python manage.py migrate

# Start the server
poetry run python manage.py runserver
# Visit http://localhost:8000
```
  </Tabs.Tab>
  <Tabs.Tab>
```bash
cd myproject

# Install Python dependencies
pip install -r requirements.txt

# Run migrations
python manage.py migrate

# Start the server
python manage.py runserver
# Visit http://localhost:8000
```
  </Tabs.Tab>
</Tabs>

---

## Troubleshooting

<Tabs items={['Python Version', 'Poetry Issues']}>
  <Tabs.Tab>
```bash
# macOS
brew install python@3.12

# Ubuntu/Debian
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.12 python3.12-venv

# Windows
winget install Python.Python.3.12
```
  </Tabs.Tab>
  <Tabs.Tab>
```bash
# If Poetry is not available, use pip instead:
pip install django-cfg

# Or install Poetry first:
curl -sSL https://install.python-poetry.org | python3 -
```
  </Tabs.Tab>
</Tabs>

---

## Support the Project

Star and Fork the repository on GitHub:
[github.com/markolofsen/django-cfg](https://github.com/markolofsen/django-cfg)

---

## Next Steps

- **[First Project](./first-project)** - Build your first Django-CFG app
- **[Configuration](./configuration)** - Learn about settings and environment
- **[Sample Project](../../guides/sample-project/overview)** - Explore a production example
