Django Pandas Integration

0.6.7 · active · verified Thu Apr 16

django-pandas provides tools to seamlessly integrate Django models with Pandas DataFrames. It allows you to query your Django models and return the results directly as Pandas DataFrames, simplifying data analysis, reporting, and machine learning workflows within Django projects. As of version 0.6.7, it's actively maintained with releases focused on compatibility with recent Django and Pandas versions.

Common errors

```
AttributeError: 'Manager' object has no attribute 'to_dataframe'
```
cause The `DataFrameManager` has not been correctly assigned to your Django model, or you are trying to call `to_dataframe()` on Django's default manager.

fix Ensure your model definition includes `objects = DataFrameManager()`: ```python from django_pandas.managers import DataFrameManager class MyModel(models.Model): # ... fields ... objects = DataFrameManager() # Add this line ```
```
ModuleNotFoundError: No module named 'django_pandas'
```
cause The `django-pandas` library is not installed in your current Python environment.

fix Install the package using pip: `pip install django-pandas`
```
TypeError: 'DataFrameManager' object is not iterable
```
cause You are trying to iterate directly over `MyModel.objects` without first calling a queryset method (like `.all()`) or `to_dataframe()`.

fix Always call a queryset method before iterating or converting to a DataFrame. For example, `MyModel.objects.all().to_dataframe()` or `df = MyModel.objects.to_dataframe()`.

Warnings

gotcha Converting very large QuerySets to DataFrames directly can consume significant memory and impact performance, especially for tables with millions of rows. Consider filtering or chunking your data.
Fix: Apply `.filter()` or `.values()` to select specific rows/columns before calling `.to_dataframe()`. For extremely large datasets, consider iterating over chunks or using database-level aggregations first.
gotcha By default, `to_dataframe()` does not automatically include related fields (e.g., ForeignKeys) as their actual values; it typically includes their IDs. To include related object data, you need to specify them.
Fix: Use the `related` argument in `to_dataframe()` (e.g., `to_dataframe(related=['foreign_key_field__name'])`) or use `.select_related()` on your QuerySet before calling `to_dataframe()` for one-to-one/many-to-one relationships, or `.prefetch_related()` for many-to-many/one-to-many.
breaking django-pandas has specific compatibility requirements for Django and Pandas versions. Using incompatible versions can lead to unexpected errors or silent failures.
Fix: Always check the `install_requires` in the `pyproject.toml` or `setup.py` on the GitHub repository for the exact version ranges supported. As of 0.6.7, Django>=2.2 and pandas>=1.0 are required. Upgrade or downgrade your Django/Pandas installations as necessary.

Install

pip install django-pandas Install stable version

Imports

DataFrameManager

wrong:

from django_pandas import DataFrameManager

correct:

from django_pandas.managers import DataFrameManager

DataFrameManager is located within the managers submodule.

Quickstart

To use django-pandas, add `objects = DataFrameManager()` to your Django model. Then, you can call `.to_dataframe()` on your model's manager or any QuerySet to convert the results into a Pandas DataFrame. Remember to ensure your Django app is configured and migrations are run.

from django.db import models
from django_pandas.managers import DataFrameManager

# Define a simple Django model
class Product(models.Model):
    name = models.CharField(max_length=255)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    stock = models.IntegerField(default=0)
    last_updated = models.DateTimeField(auto_now=True)

    # Attach DataFrameManager to your model
    objects = DataFrameManager()

    def __str__(self):
        return self.name

# --- Usage example (in a Django shell or view) ---
# Make sure to run migrations for the Product model first.
# from myapp.models import Product # Assuming Product is in 'myapp'
# Product.objects.create(name='Laptop', price=1200.00, stock=50)
# Product.objects.create(name='Mouse', price=25.50, stock=200)

# Fetch data directly as a Pandas DataFrame
# df = Product.objects.to_dataframe()
# print(df.head())

# You can also filter before converting to DataFrame
# low_stock_df = Product.objects.filter(stock__lt=100).to_dataframe()
# print(low_stock_df)

view raw JSON →