---
title: "Citry 1.0.0 is stable"
url: https://citry.dev/blog/citry-1-0-0/
description: "Citry 1.0.0 is out. What the stable release promises, what is still experimental, how to upgrade, and what comes next."
date: "2026-11-16T00:45:00+01:00"
author: "Juro Oravec"
author_url: "/community/people/"
tags:
  - "Releases"
  - "Project updates"
---

Citry 1.0.0 is out: the first stable release of the fully typed
frontend framework for Python. Install or upgrade:


```console
python -m pip install -U "citry>=1.0.0,<2"
```


Also at 1.0.0:

- `citry-lsp`, the language server;
- the VS Code extension;
- `pygments-citry`, Citry syntax highlighting for Pygments.

## What "stable" means

Upgrades within 1.x keep what the docs describe working:

- **Patch** (1.0.1): bug fixes.
- **Minor** (1.1.0): new features. Deprecated features keep working,
  with a warning, at least until 2.0.0.
- **Major** (2.0.0): the only release that may remove or break what 1.x
  documents.

Exceptions: experimental features, and fixes that close a security
hole. While you upgrade servers one at a time between two 1.x releases,
an open page may need one reload.

The exact rules, including what counts as a breaking change and how to
pin Citry:
[Versioning and support](/about/versioning/).

## What 1.x covers

Covered: what the docs teach.

- the public Python names;
- the template syntax;
- settings and extension hooks;
- the `citry` command line;
- the browser JavaScript API;
- `citry-events/1`, the protocol server events use.

Full list: [What the promise covers](/about/versioning/#what-is-covered).

Experimental: may change in a minor release. These work and are
tested, but their design is not settled.

- component previews;
- the template analysis API, behind `citry check` and the editor;
- calling event handlers from your own server code with
  `EventsDispatcher`.

Full list: [Experimental features](/about/versioning/#experimental).

Not covered: the [UI library](/ui-library/). citry-ui stays on 0.x as
an alpha, so pin one minor release, such as `"citry-ui>=0.6.0,<0.7"`.

## Upgrade to 1.0.0

1. Upgrade to 0.9.x and follow its upgrade notes.
2. Install 1.0.0 (command at the top).

0.9.0 made the last large set of breaking changes. 1.0.0 adds a few
more, all small, listed in the
[upgrade guide](/guides/upgrading-to-1-0-0/). The one most apps notice:
the State token, the signed string that carries a component's State
(the values its event handlers need between calls) to the page, now
expires after 24 hours.

- **Who is affected:** components that set no `_max_age`.
- **What happens:** a call with an expired token does not run its
  handler, and calls from that component keep failing until the
  visitor reloads the page. In production Citry shows visitors
  nothing, so show your own message, as
  [Handle out-of-date pages](/reference/browser-apis/#out-of-date-pages)
  shows.
- **To change it:** set a longer `_max_age` on the component.

Step by step: [Upgrade to Citry 1.0.0](/guides/upgrading-to-1-0-0/).
Every change: the
[changelog](https://github.com/citry-dev/citry/blob/citry@1.0.0/CHANGELOG.md){: target="\_blank" rel="noopener"}.

## Which versions get fixes

- 0.x: no more fixes.
- 1.x: bug and security fixes go to the newest minor release, so stay
  current.
- After 2.0.0: the last 1.x minor gets security fixes for 12 months.

## What comes next

More 1.x minor releases. The
[Roadmap](https://github.com/citry-dev/citry/issues/79){: target="\_blank" rel="noopener"}
tracks what is planned. Tell me what you need most, there or on
[Discord](https://discord.gg/NaQ8QPyHtD){: target="\_blank" rel="noopener"}.

## Thank you

Thank you to everyone who tried Citry during the beta, filed issues,
asked questions on Discord, and sent pull requests. Your bug reports
shaped what 1.0.0 promises. And thank you to the
[sponsors](https://github.com/sponsors/JuroOravec){: target="\_blank" rel="noopener"}
who fund the work.

If you build something with Citry, I'd love to see it.
