Skip to content

Standalone aiogram-nav

Install navigation independently from PyPI:

uv pip install 'aiogram-nav==0.3.1'
# For persistent navigation across processes:
uv pip install 'aiogram-nav[redis]==0.3.1'

Python 3.10+ and aiogram 3.22+ within 3.x are required. Neither installation requires aiogram-idle. Navigation does not start an idle worker. The aiogram-kit distribution remains a lightweight marker; install libraries directly.

The registry and explicit input bindings support reply, inline, command and hybrid navigation. Navigation prepares rendering before external effects and commits the location after completion. It preserves partial or unknown rendering evidence rather than automatically resending it. Back preserves business drafts; Cancel invokes an explicit application hook instead of clearing arbitrary FSM fields.

For application-owned rendering, use the documented tracking mode. A single owner should perform message cleanup. See the public guide for rendering, router placement, intentional root handlers and custom coordinators.

Runnable examples and development

git clone https://github.com/ArmanAvanesyan/aiogram-kit.git
cd aiogram-kit
uv sync --frozen --all-packages --all-groups --all-extras
# Export BOT_TOKEN in your environment first.
uv run --no-sync python packages/aiogram-nav/examples/demo.py --style reply
uv run --no-sync python packages/aiogram-nav/examples/demo.py --style inline
uv run --no-sync python packages/aiogram-nav/examples/demo.py --style commands
uv run --no-sync python packages/aiogram-nav/examples/demo.py --style hybrid --fsm

Memory state is single-process, bounded and lost on restart. For Redis, use aiogram_nav.storage.redis.RedisNavigationRepository, a stable namespace and Redis 7+ standalone with noeviction. Keep the application FSM storage and normalized isolation consistent across handlers and workers. See the Redis guide and Redis example.

Callback tokens bind to the actor and conversation; stale or foreign callbacks do not authorize a transition. Reply labels and bare commands lack prompt-specific provenance. Custom presenters must honor CleanupRequest.ensure_owned before each external cleanup operation. The recovery audit describes lease loss, cleanup ownership and retained recovery evidence.

Optional Idle integration

Install aiogram-idle[nav] or aiogram-idle[nav,redis] only when needed. Construct Navigation with integration.navigation_repository and call only integration.install. See the combined guide. Navigation/activity/deadline updates are atomic; Telegram, business stores and FSM writes are external effects. Both libraries remain fully usable independently.