Pre-release

This release is a pre-release and may not be stable for production use.

django-aiogram

PyPI Python CI License

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-aiogram

# settings.py
import os

INSTALLED_APPS = [..., 'django_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_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_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_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.

Project links

Data verified by PyPI on Aug 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for corneizer from gravatar.com corneizer

Credits

Author: Oleksii Kolosiuk

GitHub Statistics

Data verified by PyPI on Aug 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python <3.15, >=3.10

Provides Extra

hiredis

Tags

aiogram bot django docker redis telegram

Classifiers

Report project as malware

Download files

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

Source Distribution

django_aiogram-4.0.0.dev0.tar.gz (401.5 kB view details)

Uploaded Source

Built Distribution

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

django_aiogram-4.0.0.dev0-py3-none-any.whl (147.6 kB view details)

Uploaded Python 3

File details

Details for the file django_aiogram-4.0.0.dev0.tar.gz.

File metadata

  • Download URL: django_aiogram-4.0.0.dev0.tar.gz
  • Upload date:
  • Size: 401.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for django_aiogram-4.0.0.dev0.tar.gz
Algorithm Hash digest
SHA256 7e4dfc27831957505f1d64daa6d08351990e8f6adca39f01921468505dd9b0cd
MD5 bd67998a8d12178cf0f5fe86e576ff7d
BLAKE2b-256 12a24790f407cf73e127e8f06b0925146d3cb1d943c3a0b836e435647c4d37b2

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_aiogram-4.0.0.dev0.tar.gz:

Publisher: publish.yml on CorneiZeR/django-aiogram

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

File details

Details for the file django_aiogram-4.0.0.dev0-py3-none-any.whl.

File metadata

File hashes

Hashes for django_aiogram-4.0.0.dev0-py3-none-any.whl
Algorithm Hash digest
SHA256 deabc11bcacbce529f3e91e14fa670248be3ab36466ce1ccf94b8802475dc74b
MD5 0e27b81152777e85bcfbb64f7672af42
BLAKE2b-256 0a3015076d49ee3f7f89bfa1a06e7b1b63208125645a4b438af116ce3b75d436

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_aiogram-4.0.0.dev0-py3-none-any.whl:

Publisher: publish.yml on CorneiZeR/django-aiogram

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

Release history Release notifications | RSS feed

This release
Pre-release

4.0.0.dev0 This release

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page