brickdjango 0.3.2

Django project scaffolding: clean project structure in one command. Easy to use, modular layout (apps, config, settings), supports venv, pipenv, poetry, uv.

BrickDjango – Django project structure made easy

BrickDjango is a Django project scaffolding tool that sets up a clean, modular project structure in one command. Create Django projects and apps with a scalable layout (config, apps, settings split by environment), environment variables, and optional Docker—easy to use on Windows, Linux, and macOS.

Django project structure • Django scaffolding • Django starter • Modular Django • One-command setup

---

Table of Contents

1. Introduction
2. Installation
3. Features
4. Quick Start
5. Creating a New Project
6. Creating a New App
7. Project Structure
8. Settings Management
9. Best Practices
10. Troubleshooting
11. Testing the project locally
12. Author

---

Introduction

BrickDjango gives you a professional Django project structure without manual setup. One command creates the folder layout, virtual environment, split settings (development/production), and .env for secrets—so you can start coding instead of wiring config.

• Brick — the building block: modularity, foundation, simplicity.
• Django — the Python web framework you already use.

Why BrickDjango?

• Easy to use — brickdjango startproject myapp and you get a ready-to-run project.
• Clear project structure — apps/ for your apps, config/settings/ for base/dev/prod, base/ for shared code.
• Flexible — choose venv, pipenv, poetry, or uv; works on any OS.
• Scalable — layout that stays clean as the project grows.

---

Installation

Requirements

• Python 3.8 or higher
• pip (Python package manager)

Install from PyPI

pip install brickdjango

CLI options

After installation, the brickdjango command is available:

brickdjango --version   # or -v
brickdjango --help      # or -h

---

Features

• Easy Django project structure — one command creates a modular layout: apps/, config/, base/
• Cross-platform — works on Windows, Linux, and macOS (paths, venv Scripts/bin, UTF-8 file I/O)
• Modular project layout — apps/ for apps, config/settings/ for base/development/production, base/ for shared code
• CLI — startproject and startapp with a single command (startapp is project-independent, like django-admin startapp)
• Automatic app namespacing — when run from a BrickDjango project root, apps are created as apps.<app_name> under apps/
• Environment-based settings — base.py, development.py, production.py
• Environment variables — django-environ and .env in config/settings/
• Docker — generated project includes a Dockerfile when you choose venv or uv (it uses requirements.txt; pipenv/poetry projects use Pipfile/pyproject.toml instead)
• Virtual environment — choose venv, pipenv, poetry, or uv when creating a project; the tool creates and uses that environment and installs Django and django-environ in it

---

Quick Start

# Create a new project (you will be asked to choose: venv, pipenv, poetry, or uv)
brickdjango startproject mysite
cd mysite

# Activate or use the environment you chose, then run the server:
#   venv:   source venv/bin/activate  (or venv\Scripts\activate on Windows), then  python manage.py runserver
#   pipenv: pipenv run python manage.py runserver  (or pipenv shell first)
#   poetry: poetry run python manage.py runserver  (or poetry shell first)
#   uv:     uv run python manage.py runserver

To add an app: run from any directory (like django-admin startapp). From a BrickDjango project root, the app is created under apps/ and registered as apps.<app_name>.

brickdjango startapp blog

Then add the app to your settings (CUSTOM_APPS in a BrickDjango project, or INSTALLED_APPS otherwise).

---

Creating a New Project

brickdjango startproject <project_name>

You will be prompted to choose a virtual environment type:

Choice	Tool	Description
1	venv	Standard library venv (default)
2	pipenv	Pipenv – creates Pipfile and .venv
3	poetry	Poetry – creates pyproject.toml and .venv
4	uv	uv – creates .venv and installs with uv

• venv: No extra install; uses the Python you run brickdjango with. Creates a venv/ directory.
• pipenv / poetry / uv: Must be installed and on your PATH. The tool will create the project directory, then run the chosen tool there to create the environment and install Django and django-environ.

This command then:

• Creates the project directory and the chosen environment
• Installs Django and django-environ in that environment
• Runs django-admin startproject config to create the Django project
• Creates the BrickDjango layout (config/settings, apps, base), writes base.py, development.py, production.py, and .env (with SECRET_KEY)
• Adds .gitignore; for venv or uv also adds requirements.txt and Dockerfile (for pipenv or poetry these are omitted; use Pipfile or pyproject.toml)

Example:

brickdjango startproject mysite
# Enter choice (1-4) [default: 1]: 1
cd mysite
source venv/bin/activate   # or use pipenv/poetry/uv as chosen
python manage.py runserver

Success output: You will see the project path, the environment used, and next steps (how to activate/run and how to create apps).

---

Creating a New App

brickdjango startapp <app_name>

Independent of the project — like django-admin startapp, this command does not require manage.py. You can run it from any directory. It uses Django’s startapp under the hood.

• When run from a BrickDjango project root (a directory that contains manage.py): the app is created inside apps/<app_name>/, and apps.py is set to name = 'apps.<app_name>'. Add 'apps.<app_name>' to CUSTOM_APPS in config/settings/base.py.
• When run from any other directory: the app is created in the current directory as <app_name>/. Add '<app_name>' to INSTALLED_APPS in your Django settings.

Example (from project root):

cd mysite
brickdjango startapp blog

This creates apps/blog/ and configures apps/blog/apps.py as:

from django.apps import AppConfig

class BlogConfig(AppConfig):
    default_auto_field = 'django.db.models.BigAutoField'
    name = 'apps.blog'

Register the app in config/settings/base.py by adding it to CUSTOM_APPS:

CUSTOM_APPS = [
    'apps.blog',
]

(INSTALLED_APPS is built from DEFAULT_APPS + THIRDPARTY_APPS + CUSTOM_APPS in base settings.)

---

Project Structure

BrickDjango’s project structure is simple and scalable. After brickdjango startproject myproject, you get:

myproject/
├── base/                 # For shared utilities and common code
│   └── __init__.py
├── apps/
│   └── __init__.py       # Your apps go here (e.g. apps/blog/)
├── config/
│   ├── settings/
│   │   ├── __init__.py
│   │   ├── base.py       # Common settings, INSTALLED_APPS, etc.
│   │   ├── development.py
│   │   ├── production.py
│   │   └── .env          # SECRET_KEY and other env vars
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py
├── manage.py
├── requirements.txt   # only for venv/uv (pipenv/poetry use Pipfile/pyproject.toml)
├── Dockerfile         # only for venv/uv
├── .gitignore
└── venv/

---

Settings Management

Base settings are derived from the Django version installed in the project (the one used when you run brickdjango startproject). The tool reads the settings file that Django generates and turns it into config/settings/base.py (adding environ, SECRET_KEY from env, and the DEFAULT_APPS / CUSTOM_APPS structure). That way you get the same defaults and any new settings that come with newer Django versions, instead of a fixed template.

Settings are split by environment:

File	Purpose
config/settings/base.py	Shared settings, SECRET_KEY from env, INSTALLED_APPS
config/settings/development.py	Debug, local DB, dev-only config
config/settings/production.py	Production (e.g. DEBUG = False)

The default manage.py uses:

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings.development')

For production, set DJANGO_SETTINGS_MODULE=config.settings.production (and configure ALLOWED_HOSTS and your database in production settings).

Secret key: The generated project puts SECRET_KEY in config/settings/.env. Keep .env out of version control.

---

Best Practices

• From a BrickDjango project root, run brickdjango startapp <app_name> so apps live under apps/ with apps.<app_name>.
• Register new apps only in CUSTOM_APPS in config/settings/base.py.
• Put shared code in base/ (e.g. base/utils/).
• Use development.py for local work and production.py for deployment.
• Add a .env.example (without secrets) to the repo; keep .env in .gitignore.

---

Troubleshooting

"Error: A project named '...' already exists at ..."

• A directory with that project name already exists in the current folder. Choose another name or use a different parent directory.

"Error: An app or directory named '...' already exists at ..."

• An app or folder with that name already exists at the target path (either in the current directory or under apps/). Choose a different app name or remove the existing folder.

Django not found when running startapp

• brickdjango startapp runs django-admin startapp under the hood. Ensure Django is installed in the environment where you run brickdjango (e.g. pip install brickdjango installs Django as a dependency).

"Error: pipenv / poetry / uv is not installed or not on PATH"

• If you chose pipenv, poetry, or uv when creating a project, that tool must be installed and available on your PATH. Install it before running brickdjango startproject, or choose 1 (venv) which uses only the standard library.

---

Testing the project locally

Use these steps to run and test the package on your machine without publishing to PyPI.

1. Install in editable mode

From the project root (where setup.py and pyproject.toml are):

cd /path/to/custom_package
python -m venv venv
# Activate the venv:
#   Linux/macOS: source venv/bin/activate
#   Windows:     venv\Scripts\activate
pip install -e .

After this, the brickdjango command uses your local code. Edits to the package are picked up without reinstalling.

2. Check the CLI

brickdjango --version
brickdjango --help

3. Test startproject

Create a test project in a temporary directory (so you can delete it after):

mkdir -p /tmp/brickdjango_test
cd /tmp/brickdjango_test
brickdjango startproject testproject

When prompted, choose 1 (venv) for a quick test. Then:

cd testproject
source venv/bin/activate   # or venv\Scripts\activate on Windows
python manage.py runserver

Stop the server (Ctrl+C), then try startapp from the project directory:

cd /tmp/brickdjango_test/testproject
brickdjango startapp demo

Check that apps/demo/ exists and that config/settings/base.py has the right structure (add 'apps.demo' to CUSTOM_APPS if you want to load the app).

4. Clean up (optional)

rm -rf /tmp/brickdjango_test

---

Author

Amol Balpande — [e-mail]

BrickDjango gives you a solid foundation for scalable, maintainable Django applications. We hope it helps you build great projects — one brick at a time.