Citry: Safe, fast, and smart Python frontend engineered for AI agents.
Citry is a fully typed frontend framework for Python with server events and Vue. One component can own its HTML, browser behavior, CSS, translations, and Python event handlers, so you can build an interactive interface without maintaining a separate frontend application. It is inspired by Vue and Livewire.
Citry works with FastAPI, Django, Flask, Starlette, ASGI, and WSGI applications.
Citry supports Python 3.11 through 3.15.
Citry is stable. Code that uses what the docs describe keeps working in every 1.x release, apart from experimental features and security fixes. Versioning and support says what this covers and which releases get fixes.
Our mission: a safe, reliable, and intuitive frontend ecosystem for Python.
Read the docs · Try the playground · Explore examples · Install the VS Code extension · Browse Citry UI
Catch mistakes early
We built the same app in 12 frameworks and made the same 63 mistakes in each.
More green = earlier feedback = better
Citry 1.0.0. Each bar counts only the mistakes that apply to that framework. How we measured
Python at JavaScript speed
Time until a page with 1,400 entries is usable, the second time the server builds it.
Citry 1.0.0, one run per framework. Shorter is faster. How we measured
Monitoring vulnerabilities across the ecosystem
We read 456 security advisories from other frameworks and libraries and checked Citry for each kind of bug that could apply to it.
Advisories published up to November 2026. A monthly job lists new GitHub advisories for review. How we check
Watch the tutorial:
Start with one component
Install Citry:
python -m pip install citry
Or add it to a uv project:
uv add citry
To stay on 1.x, require citry>=1.0.0,<2 in pyproject.toml (if
uv add already wrote a citry line, edit that line). Upgrades then
bring fixes and new features, and code that uses what the docs describe
keeps working:
[project]
dependencies = ["citry>=1.0.0,<2"]
Define a component in ordinary Python. Typed inputs catch misspellings and
missing values, while template_data() chooses exactly what the template can
read:
from citry import Component
class Welcome(Component):
class Kwargs:
name: str
messages: list[str]
def template_data(self, kwargs, slots):
return {
"name": kwargs.name,
"messages": kwargs.messages,
}
def css_data(self, kwargs, slots):
return {"accent": "tomato"}
template = """
<section class="welcome">
<h1>Welcome back, {{ name }}!</h1>
<ul>
<li c-for="message in messages">
{{ message }}
</li>
<li c-empty>Nothing new yet.</li>
</ul>
</section>
"""
css = """
.welcome {
border-top: 3px solid var(--accent);
}
"""
html = str(
Welcome(
name="Ada",
messages=["Build finished", "Report ready"],
)
)
Components compose through HTML-like tags. Static inputs look like ordinary
HTML attributes; prefix an input with c- when its value is a Python
expression:
<main>
<c-Welcome name="Ada" c-messages="user.inbox" />
</main>
That is most of the template language:
<c-Name>renders a component or a built-in control-flow tag.- A
c-attribute evaluates a Python expression.
Continue with the step-by-step tutorial or read the template syntax guide.
Build the whole interface in Python
Citry gives each part of an interface a clear home:
| What you need | What Citry provides |
|---|---|
| Reusable UI | Components, typed inputs, slots, composition, and error boundaries |
| Browser behavior | Vue expressions, component JavaScript, CSS, and managed assets |
| Python interactions | Server events, forms, persistent State, and targeted HTML updates |
| Internationalization | Fluent catalogs, locale-aware formatting, and server/browser translations |
| Production control | Caching, HTML fragments, strict CSP support, CSRF hooks, and debug tooling |
| Editor help | Highlighting, completion, navigation, diagnostics, and safe formatting |
Learn these features through the component guides, Events documentation, and advanced guides.
Need ready-made application components? Install Citry UI for accessible forms, dialogs, navigation, feedback, data display, theming, and translated default labels:
python -m pip install citry-ui
Connect a web application
Mount Citry on the web framework that already serves your application. For example, with FastAPI or Starlette:
from citry import citry
from citry.contrib.fastapi import mount
mount(app, citry)
citry.initialize()
Citry includes adapters for:
| Host | Integration |
|---|---|
| FastAPI / Starlette | citry.contrib.fastapi.mount() |
| Django | citry.contrib.django.urlpatterns() |
| Flask | citry.contrib.flask.mount() |
| Any ASGI application | citry.contrib.asgi.asgi_app() |
| Any WSGI application | citry.contrib.wsgi.wsgi_app() |
The web-framework guide shows the right startup and routing setup for each host.
Want a complete project instead of an integration excerpt? Copy the FastAPI starter or choose from the standalone, Django, Flask, ASGI, and WSGI starter matrix. The collection also includes complete Project Board and HTMX integration demos. Each project has its own dependencies, lockfile, and tests. Every web starter includes a browser interaction powered by Citry Events. The HTMX demo uses HTMX for every request and page update.
Use the editor and command line
The free Citry extension for VS Code understands the HTML, Python, JavaScript, CSS, and Fluent inside a component. It provides completion, hover help, navigation, references, diagnostics, and safe formatting. The same extension is available from Open VSX.
Citry also installs a command-line checker:
citry check --static
Point it at an application for registered component contracts and template data:
citry --app myproject.app:citry_app check
See the VS Code guide and CLI reference for setup and CI usage.
Work with a coding agent
Point your agent at Citry's documentation index and your project's setup and test commands. The AI coding agents guide includes instructions for existing projects and explains the agent files included in the current starter projects. You do not need to install a Citry skill.
Performance
The benchmarks page shows how long a page with 1,400 rendered entries takes to become usable in Citry and eleven other frameworks, including Django with HTMX and Alpine, django-components, Next.js and Nuxt.
Get help and contribute
- Documentation
- Examples
- API reference
- Release notes
- Versioning and support
- Discord
- GitHub Discussions
- Issue tracker
- Contributing guide
- Sponsor Citry
Citry continues the component work begun in django-components and django-components/djc-core.
License
Metadata
Release files for citry 1.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| citry-1.1.1.tar.gz | 3.4 MB | With provenance | Details for citry-1.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| citry-1.1.1-py3-none-any.whl | Python 3 | none | any | Details for citry-1.1.1-py3-none-any.whl |
Total release size: 5.2 MB
Release files / citry-1.1.1.tar.gz
| Download URL | citry-1.1.1.tar.gz |
|---|---|
| Size | 3.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d6f666bd8edab18a5e1d8d05abf5bf222b735c9d20efb463b613ee322940fbfa
|
|
BLAKE2b-256 checksum How to use checksums |
18a0e4e1673e22d6a4907d9977c3650e642e5a7334dc67345e5e15bf48fdd123
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / citry-1.1.1-py3-none-any.whl
| Download URL | citry-1.1.1-py3-none-any.whl |
|---|---|
| Size | 1.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b3caa5738ac83b136c3439a395e81e32b40075292455e57213dd0ebc15e16245
|
|
BLAKE2b-256 checksum How to use checksums |
279fa69d51b3006ef66183e951a62de5c70cb17bb1ba3197f40fce7b102697b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for citry 1.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for citry-1.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.