django-redis-aiogram

Run aiogram next to Django: write handlers as ordinary Django app code, and send Telegram messages from anywhere in the project.

One container runs the bot. Every other process — web, Celery, a management command — pushes the call onto a Redis list and returns, so a request never waits on Telegram.

  web, celery  ──bot.send()──▶  Redis list  ──▶  start_tgbot  ──▶  Telegram

Install

pip install django-redis-aiogram

# settings.py
import os

INSTALLED_APPS = [..., 'django_redis_aiogram']

TELEGRAM_BOT = {
    'TOKEN': os.environ.get('TELEGRAM_BOT_TOKEN', ''),
    'REDIS_URL': os.environ.get('REDIS_URL', ''),
}

Both may be empty. Nothing connects or validates credentials at import time, so tests and migrations run without them. Requires Python 3.10–3.14, Django 5.2+, aiogram 3.30+, redis 6.2+.

Use it

# myapp/tg_router.py — imported automatically from every installed app
from aiogram import F, types

from django_redis_aiogram import bot


@bot.message(F.text == '/start')
async def start(message: types.Message) -> None:
    await message.answer('hi')

# anywhere else in the project
from django_redis_aiogram import bot

bot.send(chat_id=CHAT_ID, text='Order approved')

python manage.py start_tgbot

A router module, a call, and one process running the bot. Everything else — rate limits, per-process opt-out, healthchecks — is configuration, and it is documented rather than required. Webhook mode is the one alternative that also asks for a URL route; Webhook has the four steps.

Documentation

The wiki is the documentation. Pages live in docs/wiki/, so they are reviewed in the same pull request as the code they describe and published from master.


Installation	install, configure, run
Settings	every setting, with defaults and check ids
Handlers	routers, filters, FSM, the async ORM
Sending messages	routes, keyboards, files, errors
Testing	your suite without Redis, asserting what was queued
API	the instance, its internals, and what stays public
Delivery	how queued messages reach Telegram
Webhook	receiving updates over HTTP instead of polling
Rate limits	staying inside Telegram's published limits
Deployment	compose recipes, healthchecks, per-process opt-out
Logging	the logger and its structured fields
Event log	recording what the bot did to a table, and a signal to count it without one
Serialization	what can be queued
Troubleshooting	symptoms and their usual causes
Upgrading	what each major release changed, and what you must do
AI assistants	the brief to hand a coding agent

Upgrading to 3.0: the deprecated telegram_bot package name is gone, so INSTALLED_APPS and imports have to name django_redis_aiogram. The upgrading page lists everything else that needs attention.

Contributing

CONTRIBUTING.md for the workflow, AGENTS.md for the same ground in the form coding agents read. Changes are in CHANGELOG.md; security reports go through SECURITY.md.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_redis_aiogram-3.1.0.tar.gz (392.9 kB view details)

Uploaded Aug 21, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

django_redis_aiogram-3.1.0-py3-none-any.whl (144.0 kB view details)

Uploaded Aug 21, 2026 Python 3

File details

Details for the file django_redis_aiogram-3.1.0.tar.gz.

File metadata

Download URL: django_redis_aiogram-3.1.0.tar.gz
Upload date: Aug 21, 2026
Size: 392.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for django_redis_aiogram-3.1.0.tar.gz
Algorithm	Hash digest
SHA256	`239c8514d03631e38a502e725a605b3055648032d22096a4291b76a6a40fe568`
MD5	`bf6ad8c0c5ed2dab962c4814038b4ed6`
BLAKE2b-256	`1e7f128c90b5365cad20d86d16531a238ae80d029d50c006528bdea7f6033ee2`

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_redis_aiogram-3.1.0.tar.gz:

Publisher: publish.yml on CorneiZeR/django-redis-aiogram

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: django_redis_aiogram-3.1.0.tar.gz
- Subject digest: 239c8514d03631e38a502e725a605b3055648032d22096a4291b76a6a40fe568
- Sigstore transparency entry: 2554880170
- Sigstore integration time: Aug 21, 2026
Source repository:
- Permalink: CorneiZeR/django-redis-aiogram@5e9ae19ec27b6fa74050416e9b3cfab974a5bf54
- Branch / Tag: refs/tags/v3.1.0
- Owner: https://github.com/CorneiZeR
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@5e9ae19ec27b6fa74050416e9b3cfab974a5bf54
- Trigger Event: release