{"id":8171,"library":"flask-htmx","title":"Flask-HTMX","description":"Flask-HTMX is a Flask extension that provides an easy API for working with HTMX from within a Flask request context. It simplifies integrating HTMX into Flask applications by enhancing the global request object and offering a specialized `make_response` function for HTMX-specific headers. The current version is 0.4.0, and the library maintains an active release cadence with regular updates.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/edmondchuc/flask-htmx","tags":["flask","htmx","web development","extension"],"install":[{"cmd":"pip install flask-htmx","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core web framework that this extension builds upon. Flask-HTMX versions 0.3.2 and later support Flask >= 3.0.0.","package":"Flask"}],"imports":[{"note":"The HTMX class is exposed directly from the top-level package.","wrong":"from flask_htmx.extension import HTMX","symbol":"HTMX","correct":"from flask_htmx import HTMX"},{"note":"Use `flask_htmx.make_response` to easily add HTMX-specific response headers.","wrong":"from flask import make_response","symbol":"make_response","correct":"from flask_htmx import make_response"}],"quickstart":{"code":"from flask import Flask, render_template\nfrom flask_htmx import HTMX\n\napp = Flask(__name__)\nhtmx = HTMX(app)\n\n@app.route(\"/\")\ndef home():\n    if htmx:\n        # HTMX request, return a partial template\n        return render_template(\"partials/thing.html\")\n    # Normal browser request, return a full page\n    return render_template(\"index.html\")\n\n@app.route(\"/click-me\", methods=[\"POST\"])\ndef click_me():\n    # Example of using make_response for HTMX headers\n    from flask_htmx import make_response\n    return make_response(\"<span>Clicked!</span>\", trigger={'myEvent': 'Data'})","lang":"python","description":"This quickstart demonstrates initializing Flask-HTMX and handling both regular and HTMX-triggered requests. It shows how to conditionally render partial content for HTMX requests and how to use `flask_htmx.make_response` to add HTMX-specific response headers, like `HX-Trigger`."},"warnings":[{"fix":"Upgrade `flask-htmx` to version 0.3.2 or newer by running `pip install --upgrade flask-htmx` to ensure compatibility with Flask 3.x.","message":"Older versions of `flask-htmx` (pre-0.3.2) may not be compatible with Flask 3.0.0 and later.","severity":"breaking","affected_versions":"<0.3.2"},{"fix":"Always import and use `make_response` from `flask_htmx` when generating responses that need HTMX headers. This function provides extended arguments for common HTMX response headers.","message":"Using `flask.make_response` for responses that require HTMX-specific headers (e.g., `HX-Redirect`, `HX-Push-URL`, `HX-Trigger`) will not correctly apply these headers.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For versions prior to 0.4.0, ensure you pass `htmx=htmx` in your `render_template` call (e.g., `render_template('index.html', htmx=htmx)`). In 0.4.0 and later, it's available globally as `htmx`.","message":"Before version 0.4.0, the `htmx` object was not automatically available as a global context variable in Jinja2 templates. You had to explicitly pass it to `render_template`.","severity":"gotcha","affected_versions":"<0.4.0"},{"fix":"Include the CSRF token in your form or request data. For example, if using Flask-WTF, ensure your form includes `{{ form.csrf_token }}` or pass the token in hidden inputs for HTMX requests.","message":"When submitting forms via HTMX POST requests, especially if CSRF protection is enabled in Flask (e.g., with Flask-WTF), you must ensure the CSRF token is included in the HTMX request.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install flask-htmx`.","cause":"The `flask-htmx` package has not been installed in your Python environment or the virtual environment is not active.","error":"ModuleNotFoundError: No module named 'flask_htmx'"},{"fix":"Ensure you have initialized the extension either by passing the app object directly: `htmx = HTMX(app)`, or by calling `init_app()`: `htmx = HTMX(); htmx.init_app(app)`.","cause":"You are attempting to access or use the `htmx` object within a Flask request context before it has been properly initialized and registered with your Flask application.","error":"RuntimeError: The HTMX extension is not registered to the current application."},{"fix":"Replace `from flask import make_response` with `from flask_htmx import make_response` and use the provided keyword arguments for HTMX headers (e.g., `return make_response('content', trigger={'event': 'data'})`).","cause":"You are likely using `flask.make_response` instead of `flask_htmx.make_response` to construct your responses. The standard `flask.make_response` does not provide the utility to automatically set HTMX-specific headers.","error":"HTMX client-side headers (e.g., HX-Trigger, HX-Location) are not being sent or processed correctly by the browser, despite setting them in Flask."}]}