# Getting Started

Install Flasgo on Python 3.14+, build a small app, and run it locally.

Source: https://flasgo.dev/guides/getting-started/

Flasgo requires Python 3.14 or newer. These guides describe the 0.11.0 API. Start a project with `uv`:

```bash
uv init --python 3.14
uv add flasgo
```

This installs the published package. For an existing project, see [version checks and upgrades](#version-checks-and-upgrades).

Create `app.py`:

```python
import os
import secrets

from flasgo import Flasgo, Request, Response

app = Flasgo(
    settings={
        "DEBUG": True,
        "SECRET_KEY": os.environ.get(
            "FLASGO_SECRET_KEY",
            secrets.token_urlsafe(32),
        ),
        "ALLOWED_HOSTS": {"127.0.0.1", "localhost"},
        # Local HTTP only. Keep both settings True in production.
        "SESSION_COOKIE_SECURE": False,
        "CSRF_COOKIE_SECURE": False,
    }
)


@app.get("/")
async def home() -> dict[str, str]:
    return {"framework": "flasgo", "status": "ok"}


@app.post("/echo")
async def echo(request: Request) -> Response:
    payload = await request.json()
    return Response.json({"received": payload}, status_code=201)
```

Run the development server:

```bash
uv run flasgo run app.py --reload
```

Flasgo also accepts an import string:

```bash
uv run flasgo run package.module:app --reload
```

The CLI uses Uvicorn's H11 and `websockets-sansio` implementations with lifespan enabled, no `server` header, proxy-header trust disabled, bounded HTTP request heads, bounded WebSocket messages and queues, and a default concurrency limit. Flasgo also applies body, head, and read-time limits at the application boundary. Configure the production server and trusted proxy explicitly rather than copying development settings.

## Handler return values

Handlers may be synchronous or asynchronous. Flasgo converts these values into responses:

```python
@app.get("/text")
def text():
    return "plain text"


@app.get("/json")
def json_response():
    return {"ok": True}


@app.get("/created")
def created():
    return {"created": True}, 201, {"x-result": "created"}


@app.delete("/empty")
def empty():
    return None  # 204 No Content
```

You can also return `bytes`, a `list`, or a `Response` directly.

## Version checks and upgrades

Flasgo 0.11.0 is available from [PyPI](https://pypi.org/project/flasgo/0.11.0/) and [GitHub releases](https://github.com/L1ghtn1ng/flasgo/releases/tag/v0.11.0), matching the framework checkout and these guides. See the [0.11.0 changes](/overview/#flasgo-0110-changes) for upgrade considerations.

Check the version installed in your project:

```bash
uv run python -c 'from importlib.metadata import version; print(version("flasgo"))'
```

To update an existing registry installation to the newest published version allowed by its constraints:

```bash
uv lock --upgrade-package flasgo
uv sync
```

If your project pins an older version or excludes 0.11.0, update its dependency constraint first. Check the installed version after updating and run your application's tests.

For 0.11.0, upgrade SQLAlchemy to 2.0 or newer before using `flasgo db`, replace any imports of underscore-prefixed helpers from `flasgo.request` or `flasgo.session` with the private `flasgo._request` and `flasgo._session` modules, check that JWT secrets are random bytes rather than PEM, SSH, DER, or JWK text, and remove any ASGI `root_path` prefix from `DOCS_PATH`, `OPENAPI_PATH`, `METRICS_PATH`, and `OTEL_EXCLUDED_PATHS`. If you are upgrading from 0.9.1 or older, also review the [0.10.0 changes](/overview/#flasgo-0100-changes): `ALLOWED_HOSTS` and `CSRF_TRUSTED_ORIGINS` entries, parameter marker placement, route `methods` values, `after_request` hooks that now also see 404, 405, and authentication denials, empty 204 and 304 bodies, SSE heartbeat intervals, and async template rendering. If you are upgrading from 0.9.0 or older, also review the [0.9.1 changes](/overview/#flasgo-091-changes): route conflicts, boolean configuration values, session changes after exceptions, and streaming cleanup deadlines. The [0.9.0 additions](/overview/#flasgo-090-additions) remain available: response contracts and shared storage are opt-in, and switching to server-side sessions requires existing users to log in again.

## Using the development code

To work on the framework itself or test changes from a local checkout, install it in editable mode. If your project is next to the framework checkout:

```bash
uv add --editable ../flasgo
```

For Redis or Valkey support from the same checkout:

```bash
uv add --editable ../flasgo --extra redis
```

These paths refer to the framework repository, not this Astro documentation repository. Use Python 3.14 or newer. For a deployable build, use a reviewed, immutable source revision and its verified dependencies instead of a mutable editable checkout.

## Before production

- Set `DEBUG=False`.
- Load a stable `SECRET_KEY` of at least 32 characters from a secret store.
- Set `ALLOWED_HOSTS` to the service's real hostnames.
- Keep secure session and CSRF cookies enabled.
- Terminate TLS at a trusted reverse proxy or load balancer.
- Run `uv run flasgo check app.py` before deployment.

Continue with [HTTP applications](/guides/http-apps/), [Request Data and Dependencies](/guides/request-data-and-dependencies/), or [WebSockets and application lifecycle](/guides/websockets-and-lifespan/).