# aiohttp-demos: nine runnable aiohttp examples with their own datastores > The aiohttp-demos repository collects working aiohttp applications, from a Redis URL shortener and a MongoDB Twitter clone to a websockets chat and a GraphQL messenger. It is a teaching and reference resource, not a library, and it ships no releases. **aio-libs/aiohttp-demos** — Demos for aiohttp project - Repository: https://github.com/aio-libs/aiohttp-demos - Website: https://demos.aiohttp.org - Stars: 749 · Forks: 222 - Language: Makefile - License: Apache-2.0 - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/aio-libs-aiohttp-demos ## Nine applications instead of one toy endpoint aiohttp-demos is the example repository for the aiohttp project, and it is organised as a set of complete applications rather than as snippets. The catalogue covers an imagetagger deep learning image classifier, a URL shortener with Redis storage, a toxic comments classifier with a UI and an API, a Slack bot that moderates chat messages, a Twitter clone with MongoDB storage, a simple chat over websockets, a polls application with PostgreSQL storage, a blog application with PostgreSQL storage and a Redis session store, and a GraphQL messenger that is described as a simple realization of the GraphQL API. The scale of that list matters for how the repository should be used. Each demo is a program with a datastore, a UI or an API surface and a set of dependencies of its own, so a reader is not looking at a handler in isolation. A developer learning aiohttp can see how routing, templates, sessions, background work and external services fit together in a program that has to actually run. The project publishes a documentation site through Read the Docs, has a home page at demos.aiohttp.org and runs continuous integration against the master branch, with the status badge pointing at the workflow file in the repository. It sits under the Apache-2.0 licence, and the tree itself is small: a `demos/` directory of applications, a `docs/` directory, a `Makefile`, a `requirements-dev.txt` and a `LICENSE` file. ## Every demo picks a different datastore The most useful thing the collection teaches by accident is how many shapes an aiohttp application can take, because the storage choices differ across the demos. The URL shortener is described as simple and uses Redis. The Twitter clone uses MongoDB. The polls application uses PostgreSQL, and the blog application uses PostgreSQL as well but adds a Redis session store on top for sessions. The chat demo has no database at all, since it is built on websockets, and the GraphQL messenger is framed around an API surface rather than around a store. That spread is what makes the collection more than a tutorial series. A developer choosing a datastore for a new service can look at how the same framework handles a key value store, a document store and a relational store, and see which parts of the code change. The flip side is that the demos are not a coherent application. There is no shared login, no shared user model and no shared deployment story across them, so the repository cannot be run as one system. Each demo is self contained, which is exactly what you want in a reference collection and exactly what you do not want in a product. The cost of that self containment shows up in dependencies. The `Makefile` installs requirements separately for every demo, covering blog, chat, graphql-demo, imagetagger, moderator, moderator_bot, motortwit, polls and shortify, and some of those are installed from a `requirements-dev.txt` while others use a plain `requirements.txt`, which reflects that the demo directories grew at different times. ## Three machine learning demos with very different dependencies The imagetagger, the moderator and the moderator bot are the demos that pull in a model, and each does it differently. The imagetagger is an example of deploying a deep learning model with aiohttp, so the model serving pattern, where an HTTP service wraps inference and returns a prediction, is the thing to study there. The moderator is a UI and an API for classifying offensive and toxic comments, built on Kaggle data and simple logistic regression, which makes it the clearest example of the classic web stack, a page, a form and a classifier behind it. The moderator bot is a Slack bot that moderates offensive and toxic chat messages using a model from Moderator AI, an external service rather than a local model. That distinction has a practical consequence in the test setup. The `Makefile` runs the moderator bot tests with three environment variables supplied on the command line, `SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET` and `GIPHY_API_KEY`, which is a strong hint that this demo talks to outside services and that its test suite expects credentials to be present. For a reader, the three together cover the range. Imagetagger shows local model serving, the moderator shows a model trained on a public dataset and wired into a web interface, and the moderator bot shows the same classification idea reached through a third party API and a chat platform. The cost is that these three demos are the least likely to run out of the box, since each pulls a model, a dataset or a service account. ## The websockets chat and the GraphQL messenger show two API shapes Two demos exist to show how aiohttp handles a non traditional request. The chat is a simple chat using websockets, so the transport is a persistent connection rather than a request and response cycle, and the interesting part of the code is the message loop and the session handling rather than a route table. The GraphQL Messenger is described as the simple realization of the GraphQL API, so it is the demo to read when you want one HTTP endpoint that accepts queries instead of a set of paths each with its own handler. Both are short, and that is the point. A websocket example that also had a database, an admin interface and a user model would teach less about websockets, and the same goes for a GraphQL example. Their narrowness is a deliberate trade that a reader of a demo repository benefits from and a reader of a starter kit would not. The polls app sits in between. It is described as a simple polls application with PostgreSQL storage, and the project notes list configuration steps such as creating a virtual environment, installing with pip and initialising the database as a done item, along with fixing and recreating the tests. A polls app needs a schema, a form and a vote count, so it is the demo where a relational model actually shows up in the code. ## Local development starts with a per demo pip install The contribution instructions are short and concrete. For local development the README lists a set of pip commands, and the first one installs the shared development requirements while the rest install individual demo packages by their directory. ```bash $ pip install -r requirements-dev.txt $ pip install demos/polls $ pip install demos/chat $ pip install demos/blog $ pip install demos/graphql-demo ``` The `Makefile` has an `install` target that does the same thing in a longer form, starting with a pip upgrade of pip, setuptools and cython, then installing the shared requirements file and one requirements file per demo. The shared file at the top level is `requirements-dev.txt`, and each demo directory carries its own. Two commands then cover the rest of the workflow. The documentation is built locally with `make doc`, and the output tells you where the built HTML file is, after which you open the `file` link from the output. Before committing, the README asks you to run `make ci` to make sure everything is in order. ```bash $ make doc ``` ```bash $ make ci ``` ## make ci runs lint, per demo tests and a spelling check The `ci` target is the project's definition of correctness, and it is worth reading because it shows exactly what is checked. It depends on three other targets, named `lint`, `test` and `doc-spelling`. The `lint` target runs flake8 over the `demos` directory, using the repository's `.flake8` configuration. The `test` target invokes pytest separately for each demo, one line per application, which keeps a failure in one demo from hiding the rest. The moderator bot line is the exception, since it passes the three credential variables described earlier. The `doc-spelling` target builds the documentation with the spelling checker, and both documentation targets pass `-W -E` to Sphinx options, which turns warnings into errors and forces a full rebuild rather than reusing cached files. That last detail is the difference between a documentation check that catches a broken reference and one that passes on a stale build. The `doc` target builds the HTML and echoes a `file://` link to the index, and the `clean` target removes `__pycache__` directories and cleans the docs tree. The continuous integration badge in the README points at the workflow file for the master branch, so these targets are what a contribution is judged against. The result is a repository whose quality bar is lint plus per application tests plus documentation, which is a reasonable bar for teaching code and a low one for production code. ## The improvement notes show where the repository stopped The README ends with an improvement plan for the polls demo, and the checklist is a candid record of the state of the work. Items marked done include creating configuration steps, fixing or recreating the tests, fixing URLs that pointed at the old aiohttp tutorial location, setting up a communication channel on the aio-libs Gitter room, and adding a Contributing section. Items still marked as not done are adding a What's next section and discussing a roadmap, and several entries are marked as in progress, including revising `tutorial.rst` and creating missing issues. Read together, those notes describe a repository that is maintained at the level of keeping the examples running and the documentation building, rather than at the level of growing a product. There are no GitHub releases for this repository, so there is no version history to consult and no upgrade path to follow. The last push was on 2026-10-19 and the default branch is `master`, which means the working copy is where changes land. For a reader deciding whether to use a demo as a starting point, that is the important context. The code is a reference, the licence is permissive, and the surrounding machinery, flake8, pytest, Sphinx and the CI workflow, is the kind of scaffolding worth copying. The roadmap items that are still open tell you which parts are known to be incomplete. ## Copying a demo versus writing the application yourself The alternative to this repository is to start from the aiohttp documentation's own example and build up. That path gives you a smaller surface, no datastores to install and no third party services to configure, and it keeps the result entirely yours from the first line. It is the right choice for a service with unusual requirements, because none of the demos model anything you do not need. The alternative to a framework is to use a synchronous web framework instead. The difference in approach is visible in the structure of each demo: an asyncio application is a single event loop handling many connections, so long operations such as a database call have to be thought about rather than being a blocking function in a thread pool. Demos such as the polls app and the blog app, with real storage and sessions, show that shape, and the chat demo shows what it looks like when the connection never closes. The third option is a framework that arrives with its own generator, ORM and admin interface. That gives more structure per file and less code to write, and it also brings assumptions about how the project should be organised. The demos in this repository deliberately make none of those assumptions, which is why they are useful to read and why they are not a place to start a real service without rewriting them. ## Conclusion aiohttp-demos is a good fit for a developer who wants to read a complete aiohttp application, or to copy one service pattern such as the Redis backed shortener, the PostgreSQL polls app or the websockets chat, and then own the copy. It is the wrong source for a maintained library or a framework to depend on, since it publishes no releases and its improvement notes still list open items. Before copying anything, check that the demo's dependencies still install, that its datastore requirement matches what you run, and that the aiohttp version you use matches the one the example was written against, since the repository has no version tags to guide that choice. ## FAQ ### What is the aiohttp-demos repository used for? It collects demos for the aiohttp project, described in the README as examples for that project. The applications include a URL shortener with Redis storage, a Twitter clone with MongoDB storage, a polls app with PostgreSQL, a blog with PostgreSQL and a Redis session store, a websockets chat and a GraphQL messenger. ### How do I install the aiohttp demos for local development? Install the shared development requirements with `pip install -r requirements-dev.txt` and then install the individual demos you need, for example `pip install demos/polls`. The Makefile has an `install` target that performs the same steps for every demo, starting with `pip install -U pip setuptools cython`. ### What does make ci do in aiohttp-demos? The `ci` target runs `lint`, `test` and `doc-spelling` in sequence. Lint runs flake8 over the demos directory, test runs pytest separately for each demo, and the spelling check builds the documentation with Sphinx options that turn warnings into errors. ### Why do the aiohttp-demos tests need environment variables? The Makefile runs the moderator bot tests with `SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET` and `GIPHY_API_KEY` set on the command line, because that demo works against a Slack bot and the Moderator AI service. It is the one test line in the target that does not follow the plain per demo pattern. ### Does aiohttp-demos publish releases I can pin to? No, the repository has no GitHub releases. The last push was on 2026-10-19 and the default branch is `master`, and the README's improvement notes still list open items for the polls demo, including a What's next section and a roadmap discussion. ## Sources - [aio-libs/aiohttp-demos on GitHub](https://github.com/aio-libs/aiohttp-demos) - [Issues](https://github.com/aio-libs/aiohttp-demos/issues) - [License: Apache-2.0](https://github.com/aio-libs/aiohttp-demos/blob/master/LICENSE) - [Project website](https://demos.aiohttp.org) - [README](https://github.com/aio-libs/aiohttp-demos/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aio-libs-aiohttp-demos