Install Beanie ODM in Python

Beanie is a modern Object-Document Mapper (ODM) for Python. It works with MongoDB and asyncio to handle database operations. This guide shows you how to install Beanie ODM in Python quickly and correctly.

We will cover setting up a virtual environment, installing Beanie with pip, and verifying the installation. You will also see a simple code example to confirm everything works.

Prerequisites

Before you install Beanie, make sure you have Python 3.7 or higher. You also need pip installed. Check your Python version using the terminal.

python --version
# Output: Python 3.9.7

You should have MongoDB running locally or have access to a remote MongoDB instance. Beanie connects to MongoDB asynchronously.

Step 1: Create a Virtual Environment

Always use a virtual environment to keep your project dependencies isolated. This prevents conflicts with other Python projects.

Open your terminal and navigate to your project folder. Then run the following command.

python -m venv beanie_env

Activate the virtual environment. On Windows use:

beanie_env\Scripts\activate

On macOS or Linux use:

source beanie_env/bin/activate

You will see the environment name in your terminal prompt. This confirms the environment is active.

Step 2: Install Beanie with pip

Now install Beanie using pip. Run the command below.

pip install beanie

This command downloads Beanie and all its dependencies, including motor for async MongoDB access. The process takes a few seconds.

To install a specific version, use pip install beanie==1.19.0. Replace the version number with your desired version.

Step 3: Verify the Installation

Check if Beanie installed correctly. Open a Python interactive shell or create a test file.

# test_install.py
import beanie
print(beanie.__version__)

Run the script.

python test_install.py
# Output: 1.19.0

If you see a version number, the installation succeeded. If you get an import error, try reinstalling or check your virtual environment.

Step 4: Quick Example with Beanie

Let us write a small example to confirm Beanie works with MongoDB. We will define a simple document model and insert one record.

# example.py
import asyncio
from beanie import init_beanie, Document
from motor.motor_asyncio import AsyncIOMotorClient

# Define a Beanie document
class Student(Document):
    name: str
    age: int

    class Settings:
        name = "students"  # collection name

async def main():
    # Connect to MongoDB
    client = AsyncIOMotorClient("mongodb://localhost:27017")
    await init_beanie(database=client.school, document_models=[Student])

    # Create a new student
    student = Student(name="Alice", age=22)
    await student.insert()

    # Fetch and print
    fetched = await Student.find_one(Student.name == "Alice")
    print(f"Found: {fetched.name}, Age: {fetched.age}")

asyncio.run(main())

Run the example.

python example.py
# Output: Found: Alice, Age: 22

This confirms Beanie connects to MongoDB and performs CRUD operations. The Document class is the base for all your models.

Step 5: Understanding Dependencies

Beanie depends on motor for async MongoDB driver and pydantic for data validation. These install automatically with Beanie.

You can see all installed packages using pip list. Look for beanie, motor, pydantic, and pymongo in the list.

pip list | grep -i beanie
# Output: beanie 1.19.0

If you need to install Beanie in a production environment, consider using a requirements.txt file. Add beanie to that file and run pip install -r requirements.txt.

Common Installation Issues

Some users face problems when installing Beanie. Here are solutions to common errors.

Error: "No module named 'beanie'"

This usually happens when you are not in the correct virtual environment. Activate the environment again or install Beanie globally if needed.

Error: "pip command not found"

Install pip first. On Ubuntu use sudo apt install python3-pip. On Windows ensure Python is added to PATH.

Error: "MongoDB connection refused"

This is not a Beanie installation issue. Make sure MongoDB is running. Use mongod to start the server.

Best Practices for Beanie Installation

Always use a virtual environment. This keeps your project clean and avoids version conflicts. Consider using poetry or pipenv for advanced dependency management.

Pin your Beanie version in production. Use beanie==1.19.0 in your requirements file to ensure consistent behavior across deployments.

Test the installation with a simple script before building complex applications. This saves time debugging later.

Conclusion

Installing Beanie ODM in Python is straightforward. You created a virtual environment, installed Beanie with pip, and verified the setup with a working example. Beanie simplifies working with MongoDB in async Python applications.

Now you can start building data-driven apps with clean models and fast database operations. Remember to keep your dependencies updated and test your setup regularly.