FastAPI Initializer

An interactive CLI tool that scaffolds production-ready FastAPI projects with sensible defaults - so you can skip the boilerplate and start building right away.

---

✨ What Does It Do?

Run a single command, answer a few prompts, and get a fully structured FastAPI project with:

• 🗂️ Clean project layout - api/, core/, models/, schemas/, services/
• 🗃️ Database support - SQLite, MySQL, or PostgreSQL
• 🔧 ORM of your choice - SQLAlchemy or SQLModel
• 🧪 Testing setup - pytest / pytest-asyncio with httpx, ready to go
• 🧹 Linter config - Black or Ruff
• 🐳 Docker ready - optional Dockerfile & docker-compose.yml
• ⚙️ Environment config - pydantic-settings with .env support
• 📖 Documentation - every folder gets a README explaining its purpose

---

📦 Installation

Recommended: Install Globally

Install fastapi-initializer as a global CLI tool — no virtual environment needed. Just install once and use the fastapi-init command from anywhere, just like uv, pip, or ruff.

Using pipx:

pipx install fastapi-initializer

Or using uv:

uv tool install fastapi-initializer

Alternative: Install with pip

If you prefer a traditional install inside a virtual environment:

pip install fastapi-initializer

Install from Source (for development)

# Clone the repository
git clone https://github.com/DasunNethsara-04/fastapi-initializer.git
cd fastapi-initializer

# Create a virtual environment and install dependencies
uv sync

# Run the CLI directly
uv run fastapi-init my-project

---

🚀 Usage

fastapi-init my-project

You'll be guided through interactive prompts:

❯ FastAPI Initializer
Creating project: my-project

❯ What kind of database do you want to use?
  > SQLite / MySQL / PostgreSQL / None

❯ Which ORM do you want to use?
  > SQLAlchemy / SQLModel / None

❯ What linter do you want to use?
  > Ruff / Black / None

❯ What testing framework do you like to use?
  > PyTest / pytest-async-io / None

❯ Do you want to create a Docker file for this project?
  > Yes / No

✔ FastAPI project 'my-project' created successfully!

Then get started in seconds:

cd my-project
uv sync
uv run uvicorn app.main:app --reload

Open http://127.0.0.1:8000/docs to see the interactive API docs.

---

Screenshorts

---

📁 Generated Project Structure

The generated project follows a modular, production-style layout:

my-project/
├── app/
│   ├── api/
│   │   ├── v1/
│   │   │   └── users.py            # User endpoints
│   │   ├── __init__.py              # Mounts versioned routers
│   │   └── deps.py                  # Shared dependencies (e.g. auth)
│   ├── core/
│   │   ├── config.py                # App settings via pydantic-settings
│   │   └── security.py              # OAuth2 / auth utilities
│   ├── models/
│   │   └── user.py                  # ORM model (SQLAlchemy / SQLModel)
│   ├── schemas/
│   │   └── user.py                  # Pydantic request / response models
│   ├── services/
│   │   └── user_service.py          # Business logic layer
│   ├── db/
│   │   ├── base.py                  # ORM Base class
│   │   └── session.py               # Engine & get_session() dependency
│   └── main.py                      # FastAPI app entry-point
├── tests/
│   └── test_users.py                # Smoke test with httpx
├── .env                             # Environment variables
├── .gitignore
├── pyproject.toml
├── Dockerfile                       # (optional)
├── docker-compose.yml               # (optional)
└── README.md                        # Auto-generated project docs

Note: Folders like models/, db/, tests/, and Docker files are only generated when you select the corresponding options.

What Each Folder Does

Folder	Purpose
app/api/	HTTP route definitions, versioned (v1/, v2/, …).
app/core/	App-wide settings (Settings class) and security helpers.
app/models/	ORM model classes mapped to database tables.
app/schemas/	Pydantic models for request validation and response serialisation.
app/services/	Business-logic layer — keeps route handlers thin and testable.
app/db/	Database engine, session factory, and get_session() dependency.
tests/	Automated test suite using pytest + httpx.

---

🛠️ Configuration Options

Prompt	Choices	What It Generates
Database	SQLite, MySQL, PostgreSQL, None	app/db/session.py with connection URL and driver dependency
ORM	SQLAlchemy, SQLModel, None	app/models/ with model classes and app/db/base.py
Linter	Ruff, Black, None	Adds the linter to pyproject.toml dependencies
Test framework	pytest, pytest-asyncio, None	tests/ directory with async smoke test
Docker	Yes, No	Dockerfile, docker-compose.yml, .dockerignore

---

🤝 Contributing

Contributions are welcome! Here's how to get started:

# 1. Fork and clone
git clone https://github.com/DasunNethsara-04/fastapi-initializer.git
cd fastapi-initializer

# 2. Install dependencies
uv sync

# 3. Make your changes, then test
uv run fastapi-init test-project

# 4. Submit a pull request

---

📄 License

This project is licensed under the MIT License.

---

🙏 Acknowledgements

Built with:

• FastAPI - the framework this tool scaffolds
• Typer - CLI framework
• InquirerPy - interactive prompts