Beanie maps one Document class per MongoDB collection, and its README example ends mid-comment

Every collection is expected to have a Document class

Beanie is an asynchronous Python object-document mapper for MongoDB, and its unit of work is one class per collection. Each database collection gets a corresponding Document that is used to interact with that collection, and through it documents are retrieved, added, updated or deleted. The models sit on Pydantic, so a field is declared the way it would be declared in any Pydantic model rather than in a separate schema language, which is what makes database documents and request bodies share one set of classes. Two consequences follow from that arrangement. The verbs live on the class rather than on a session object, and data plus schema migrations are handled by the library itself instead of by a separate migration tool, which the project calls out as supported out of the box. Its stated payoff is time saved on boilerplate. A synchronous version of the same design exists as a separate project, Bunnet, kept under the same author's account.

The README example stops one word into its own comment

The single code sample in the README defines two classes and then breaks off mid-sentence. What arrives first is the import list and the model definitions: asyncio, AsyncMongoClient from pymongo, BaseModel from pydantic, and Document, Indexed and init_beanie from beanie, followed by a Category model with two required strings and a Product document carrying a name, an optional description, an indexed price and a nested category. The final line is a comment reading `# This is an asynchron`, and the text ends there. Nothing visible calls init_beanie, opens a query, or enters an event loop, so the part that connects a model to a running MongoDB client is absent, and the asyncio and AsyncMongoClient imports go unused by the lines that follow. Copying this block yields model definitions and nothing else:

import asyncio
from typing import Optional

from pymongo import AsyncMongoClient
from pydantic import BaseModel

from beanie import Document, Indexed, init_beanie

class Category(BaseModel):
    name: str
    description: str

class Product(Document):
    name: str                          # You can use normal types just like in pydantic
    description: Optional[str] = None
    price: Indexed(float)              # You can also specify that a field should correspond to an index
    category: Category                 # You can include pydantic models as well

# This is an asynchron

Indexed and nested fields are declared in the class body

Three field styles sit next to each other in that Product class, and inline comments say what each one is for. A plain `str` name carries the remark that normal Pydantic types work as usual. `description` is typed `Optional[str]` with a None default, so the field is optional at the model level. `price` is wrapped in `Indexed(float)`, which the comment describes as specifying that a field should correspond to an index, and that single wrapper is the only piece of database structure the sample shows. `category` is typed as Category, an ordinary Pydantic model, with the note that Pydantic models can be included as well, so the document embeds an object instead of pointing at another collection. In four lines the sample covers a scalar field, an optional field, an indexed field and an embedded model. What it does not show is index creation on the MongoDB side. The article list does include a separate post on MongoDB indexes with Beanie, which is where that half is written up.

Two installers, and extras named after clouds

Installation is given twice, once for pip and once for Poetry: `pip install beanie` and `poetry add beanie`. Everything past the base install sits in extras, and the prose does not enumerate them; it points at the optional dependencies section of docs/getting-started.md and names three as examples, aws, gcp and srv. Those names line up with the optional-dependencies groups in pyproject.toml, which also carries test and doc groups. The test group is the most detailed: pre-commit, pytest with pytest-asyncio and pytest-cov, dnspython, pyright, asgi-lifespan, httpx, pydantic-settings, pydantic-extra-types, time-machine, and fastapi held below 0.130.0. The doc group holds the documentation toolchain, Pygments, Markdown, pydoc-markdown, mkdocs with its material theme, and jinja2. A third group belongs to a package this project does not own, and the file cuts off in the middle of its constraint at `queue = ["beanie-batteries-queue>=0.`, so where that version range starts is the last thing the file says before it stops.

pymongo 4.15.0 is excluded and click is a runtime dependency

The runtime dependency list is short and unusually specific. pydantic is held to the 2.x line as `pydantic>=2.4,<3.0`, which puts a floor under the model layer Beanie is built on. pymongo appears as `pymongo>=4.11.0,!=4.15.0,<5.0.0`, so one exact release, 4.15.0, is carved out of an otherwise wide range, and no comment in the file says why that version is excluded. Three smaller entries complete the set: click at a floor of 7, lazy-model between 0.4.0 and 1.0.0, and typing-extensions from 4.7. click is the odd one for a library, being the command line parsing package, while the README describes no command that gets installed and the sample offers Python imports rather than a console entry point. lazy-model has no prose explanation either. Both are installed on every Beanie install whether or not the code being written touches a terminal or a lazy model.

Python 3.10 to 3.13, and the version number lives outside the metadata

Supported interpreters are declared twice and the two declarations agree. requires-python reads >=3.10,<3.14, and the classifiers repeat 3.10, 3.11, 3.12 and 3.13 one by one, alongside a 3 only marker, Typing :: Typed, OS Independent, and a Development Status of 5, Production/Stable. The ceiling matters as metadata rather than as documentation: an upper bound in requires-python is enforced by installers, so a newer interpreter is refused rather than warned about. The build runs through flit, with flit_core between 3.11 and 5 and flit_core.buildapi as the backend. Version is listed under dynamic, so the number is not written in pyproject.toml at all and is read from the package source during the build. That is why a file search does not turn up a version to compare with the 2.2.0 tag published on 2026-08-31, preceded by 2.1.0 in March and 2.0.1 in November 2025.

The project links still address roman-right/beanie

The repository is BeanieODM/beanie, yet every repository link inside the README points at roman-right/beanie: the overview line, the documentation bullet and the resources bullet alike. The homepage is the documentation domain beanie-odm.dev rather than a GitHub path, so the tutorial, the API reference, the changelog and the Discord invite are all reached by domain instead. That link list is also the clearest record of what Beanie is deployed alongside. All five example projects pair it with FastAPI: an activity log and notification service running against DocumentDB as a MongoDB-compatible store, a JWT authentication sample, an Azure Cosmos sample, a rating predictor with a React front end, and a URL shortener using JWT and OAuth2. One sibling project is named in the overview rather than as a dependency, Bunnet, the synchronous version of the same mapper.

Editorial conclusion

Beanie is a reasonable pick for a FastAPI service that wants Pydantic models to double as MongoDB document classes, and the constraints in its packaging are specific enough to check before committing: Python 3.10 through 3.13, pydantic 2.x, pymongo 4.11 or newer with 4.15.0 excluded, and no released CLI despite click being a runtime dependency. Verify two things for yourself. The README example is incomplete, so take the initialization and query patterns from the documentation site rather than from the front page, and remember that Bunnet is the synchronous counterpart if you are not running an async stack. Version numbers come from the package source rather than from pyproject.toml, so pin releases by tag and not by what the metadata file appears to say.

Frequently asked questions

Official sources

1. BeanieODM/beanie on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases