Setup

Requirements

Hyperflask simplifies development environments by standardizing everything around containers.

VS Code is also the recommended editor (and currently the only one with syntax highlighting for Jinjapy files).

What you will need:

• A UNIX like system (Linux, MacOS or WSL on Windows)
• Docker
• VS Code with the Dev Containers extension

Python is not needed on your machine, everything will be executed inside containers.

Additional VS Code extensions will be suggested when you open a project:

• Python
• SQLORM Syntax Highlighting
• Jinjapy Language Support

Starting a new project using Hyperflask-Start

Hyperflask-Start is the starter kit for Hyperflask projects. It is the recommended experience.

Launch the following command to create your project:

curl -L https://raw.githubusercontent.com/hyperflask/hyperflask-start/main/start.sh | bash

This will prompt you for some options and create the project in a new folder.

Note

The start.sh script is very simple and uses a container to create a new project using cookiecutter.
To directly create a project using cookiecutter, run the following command:

cookiecutter gh:hyperflask/hyperflask-start

Launching using VS Code and dev containers

Open your project folder in VS Code. It should prompt you to "re-open workspace in development container" which you should accept. VS Code will create and start the development container and re-launch itself.

You are now developping from the container inside which you will find recent versions of Python, Node & npm and hyperflask installed.

Once your VS Code workspace is ready, start your app in a VS Code Terminal:

uv run hyperflask dev

Advanced

Although VS Code with dev containers is the recommended experience, it is not mandatory. Hyperflask apps are standard python apps and you can install their requirements in a virtualenv and start a server using the CLI.

Launching without dev containers

First create a project using Hyperflask-Start.

1. Ensure that your system meet the requirements:
   • Python (>=3.10)
   • uv
   • nodejs (>=22)
2. Run npm install
3. Launch app using uv run hyperflask dev

Launching with devcontainers-cli

If you are not using VS Code but want to use dev containers, a CLI tool is available:

1. Install devcontainers-cli
2. Start dev container: devcontainer up --workspace-folder .
3. Launch your app: devcontainer exec uv run hyperflask dev

Installation without Hyperflask-Start

Warning

All the documentation assumes you are using Hyperflask-Start

This installation method works with any python package manager

1. Ensure that your system meet the requirements
2. Create your project directory: mkdir example-project && cd example-project
3. Create and activate a virtualenv: python -m venv .venv && source .venv/bin/activate
4. pip install hyperflask
5. Run npm install esbuild tailwindcss @tailwindcss/cli htmx.org htmx-ext-sse bootstrap-icons daisyui
6. Run mkdir pages && echo "Hello world" > pages/index.jpy
7. Start a development server using hyperflask dev