Installation Guide

Get LightAPI up and running in your development environment. This guide covers installation, dependencies, and environment setup.

Requirements

LightAPI requires Python 3.10 or higher and supports the following platforms:

Python: 3.10, 3.11, 3.12, 3.13
Operating Systems: Linux, macOS, Windows
Databases: SQLite, PostgreSQL, MySQL (via SQLAlchemy)

Installation Methods

Method 1: uv (Recommended)

uv add lightapi

Method 2: pip

pip install lightapi

Method 3: Development Installation

git clone https://github.com/iklobato/lightapi.git
cd lightapi
uv sync --extra dev

Method 3: Virtual Environment (Recommended)

Create an isolated environment for your project:

# Create virtual environment
python -m venv lightapi-env

# Activate virtual environment
# On Linux/macOS:
source lightapi-env/bin/activate
# On Windows:
lightapi-env\Scripts\activate

# Install LightAPI
pip install lightapi

Core Dependencies

LightAPI v2 ships with these pinned core dependencies:

Package	Version	Purpose
`sqlalchemy`	`>=2.0`	ORM and imperative mapping
`pydantic`	`>=2.0`	Schema validation
`starlette`	`>=0.37`	ASGI framework
`uvicorn`	`>=0.30`	ASGI server
`pyjwt`	`>=2.8`	JWT authentication
`redis`	`>=5.0`	Response caching
`pyyaml`	`>=6.0`	YAML configuration

Optional Extras

Async I/O (`lightapi[async]`)

Activate fully async database I/O by installing the async extra:

uv add "lightapi[async]"
# or: pip install "lightapi[async]"

This installs:

Package	Purpose
`sqlalchemy[asyncio]`	Async SQLAlchemy core
`asyncpg`	PostgreSQL async driver
`aiosqlite`	SQLite async driver
`greenlet`	Required by SQLAlchemy async

Then swap create_engine for create_async_engine:

# Before (sync)
from sqlalchemy import create_engine
engine = create_engine("postgresql://user:pass@localhost/db")

# After (async — one-line change)
from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")

See Async Support for the full guide.

Development Tools (`lightapi[dev]`)

uv add "lightapi[dev]"

Includes: pytest, pytest-asyncio, pytest-cov, httpx, aiosqlite, ruff, mypy.

Verify Installation

# verify.py
from sqlalchemy import create_engine
from lightapi import LightApi, RestEndpoint, Field

class PingEndpoint(RestEndpoint):
    message: str = Field(default="pong")

engine = create_engine("sqlite:///:memory:")
app = LightApi(engine=engine)
app.register({"/ping": PingEndpoint})
print("LightAPI installed successfully.")

python verify.py
# LightAPI installed successfully.

Verify async support:

import asyncio
from sqlalchemy.ext.asyncio import create_async_engine
from lightapi import get_async_session
from sqlalchemy import text

async def check():
    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
    async with get_async_session(engine) as s:
        result = await s.execute(text("SELECT 1"))
        assert result.scalar() == 1
    print("Async support working.")

asyncio.run(check())

Database Setup

SQLite (Default)

SQLite works out of the box with no additional setup:

from lightapi import LightApi

app = LightApi(database_url="sqlite:///my_app.db")

PostgreSQL

Install PostgreSQL server
Install Python driver:
```
pip install psycopg2-binary
```

Configure connection:

app = LightApi(database_url="postgresql://user:password@localhost:5432/mydb")

MySQL

Install MySQL server
Install Python driver:
```
pip install pymysql
```

Configure connection:

app = LightApi(database_url="mysql+pymysql://user:password@localhost:3306/mydb")

Environment Configuration

Environment Variables

Create a .env file for environment-specific settings:

# .env
LIGHTAPI_DATABASE_URL=sqlite:///development.db
LIGHTAPI_JWT_SECRET=your-secret-key-here
LIGHTAPI_REDIS_URL=redis://localhost:6379/0

Load environment variables in your application:

import os
from dotenv import load_dotenv
from lightapi import LightApi

load_dotenv()

# LightApi uses LIGHTAPI_DATABASE_URL when no engine/database_url is passed
app = LightApi(database_url=os.getenv("LIGHTAPI_DATABASE_URL"))

Docker Setup

Create a Dockerfile for containerized deployment:

FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Expose port
EXPOSE 8000

# Run application
CMD ["python", "app.py"]

Create requirements.txt:

lightapi
psycopg2-binary  # for PostgreSQL
redis           # for caching
python-dotenv   # for environment variables

Build and run:

docker build -t my-lightapi-app .
docker run -p 8000:8000 my-lightapi-app

IDE Setup

VS Code

Install recommended extensions:

{
  "recommendations": [
    "ms-python.python",
    "ms-python.black-formatter",
    "ms-python.isort",
    "ms-python.mypy-type-checker",
    "redhat.vscode-yaml"
  ]
}

PyCharm

Create new Python project
Configure Python interpreter to use your virtual environment
Install LightAPI plugin (if available)
Configure code style for Black formatting

Troubleshooting

Common Installation Issues

Issue: pip install lightapi fails with permission error

# Solution: Use user installation
pip install --user lightapi

Issue: SQLAlchemy version conflicts

# Solution: Upgrade SQLAlchemy
pip install --upgrade sqlalchemy

Issue: asyncpg installation fails on Windows

# Solution: Install Visual C++ Build Tools or use the pre-built wheel
pip install asyncpg --only-binary asyncpg

Issue: PostgreSQL driver installation fails

# Solution: Install binary version
pip install psycopg2-binary

Verification Commands

Check installed packages:

pip list | grep lightapi
pip show lightapi

Check Python version:

python --version

Test database connectivity:

from sqlalchemy import create_engine
engine = create_engine("sqlite:///test.db")
print("✅ Database connection successful")

Next Steps

Now that LightAPI is installed, you're ready to:

Quickstart Guide - Build your first API in 5 minutes
Configuration Guide - Learn about YAML and Python configuration
Tutorial - Step-by-step API development
Examples - Explore real-world examples

Getting Help

If you encounter issues during installation:

Documentation: Check our comprehensive guides
GitHub Issues: Report bugs or ask questions
Community: Join discussions and get help from other users

Installation complete! 🎉 You're now ready to build amazing APIs with LightAPI.