Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/unfoldadmin/django-unfold/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Django Import Export adds import and export functionality to your Django admin, supporting multiple formats like CSV, Excel, JSON, and YAML. Unfold’s integration provides custom-styled forms and maintains a consistent user experience throughout the import/export workflow.
Import/Export functionality is particularly useful for data migration, bulk updates, and providing users with data portability options.

​
Installation

1

Install django-import-export

Install the package using pip:
pip install django-import-export
2

Add to INSTALLED_APPS

Add both unfold.contrib.import_export and import_export to your settings:
settings.py
INSTALLED_APPS = [
    "unfold",
    "unfold.contrib.import_export",  # Must come before import_export
    
    "django.contrib.admin",
    # ...
    
    "import_export",
]

​
Basic Configuration

​
Using ImportExportModelAdmin

Configure your admin to support both import and export:
admin.py
from django.contrib import admin
from unfold.admin import ModelAdmin
from import_export.admin import ImportExportModelAdmin
from unfold.contrib.import_export.forms import ExportForm, ImportForm
from .models import Book

@admin.register(Book)
class BookAdmin(ModelAdmin, ImportExportModelAdmin):
    import_form_class = ImportForm
    export_form_class = ExportForm
    
    list_display = ["title", "author", "published_date", "isbn"]
    search_fields = ["title", "author"]
The import_form_class and export_form_class attributes ensure proper Unfold styling for all form elements.

​
Using SelectableFieldsExportForm

Allow users to choose which fields to export:
admin.py
from unfold.contrib.import_export.forms import SelectableFieldsExportForm

@admin.register(Book)
class BookAdmin(ModelAdmin, ImportExportModelAdmin):
    import_form_class = ImportForm
    export_form_class = SelectableFieldsExportForm

​
Resource Configuration

Define a Resource class to customize import/export behavior:
resources.py
from import_export import resources, fields
from import_export.widgets import ForeignKeyWidget
from .models import Book, Author

class BookResource(resources.ModelResource):
    author = fields.Field(
        column_name="author",
        attribute="author",
        widget=ForeignKeyWidget(Author, "name")
    )
    
    class Meta:
        model = Book
        fields = ["id", "title", "author", "published_date", "isbn"]
        export_order = ["id", "title", "author", "published_date", "isbn"]
        import_id_fields = ["isbn"]  # Use ISBN as unique identifier
        skip_unchanged = True
        report_skipped = True

​
Connecting Resource to Admin

admin.py
from .resources import BookResource

@admin.register(Book)
class BookAdmin(ModelAdmin, ImportExportModelAdmin):
    resource_class = BookResource
    import_form_class = ImportForm
    export_form_class = ExportForm

​
Advanced Features

​
Custom Import/Export Formats

Restrict available formats:
admin.py
from import_export.formats.base_formats import CSV, XLSX

class BookAdmin(ModelAdmin, ImportExportModelAdmin):
    formats = [CSV, XLSX]  # Only allow CSV and Excel
    import_form_class = ImportForm
    export_form_class = ExportForm

​
Field Validation and Cleaning

Add custom validation during import:
resources.py
from import_export import resources
from django.core.exceptions import ValidationError

class BookResource(resources.ModelResource):
    def before_import_row(self, row, **kwargs):
        """Validate and clean data before importing."""
        # Normalize ISBN format
        if "isbn" in row:
            row["isbn"] = row["isbn"].replace("-", "").strip()
        
        # Validate required fields
        if not row.get("title"):
            raise ValidationError("Title is required")
    
    def after_import_row(self, row, row_result, **kwargs):
        """Perform actions after importing a row."""
        # Send notification, update cache, etc.
        pass
    
    class Meta:
        model = Book
Import data with foreign key relationships:
resources.py
from import_export import resources, fields
from import_export.widgets import ForeignKeyWidget

class BookResource(resources.ModelResource):
    author = fields.Field(
        column_name="author_name",
        attribute="author",
        widget=ForeignKeyWidget(Author, "name")
    )
    
    publisher = fields.Field(
        column_name="publisher_name",
        attribute="publisher",
        widget=ForeignKeyWidget(Publisher, "name")
    )
    
    class Meta:
        model = Book
        # If author doesn't exist, create it
        skip_unchanged = True

​
Bulk Updates

Update existing records during import:
resources.py
class BookResource(resources.ModelResource):
    class Meta:
        model = Book
        import_id_fields = ["isbn"]  # Match on ISBN
        fields = ["isbn", "title", "price", "stock"]
        # This will update existing books and create new ones

​
Export Action ModelAdmin (Legacy)

This class has been removed in django-import-export 4.x as styling issues have been resolved in the core package.
For django-import-export versions prior to 4.x, use the custom ExportActionModelAdmin:
admin.py
from unfold.admin import ModelAdmin
from unfold.contrib.import_export.admin import ExportActionModelAdmin

# Only needed for django-import-export < 4.x
@admin.register(Book)
class BookAdmin(ModelAdmin, ExportActionModelAdmin):
    pass

​
User Workflow

​
Importing Data

1

Access import

Click the “Import” button on the model’s changelist page
2

Select file

Choose your data file (CSV, Excel, JSON, etc.)
3

Select format

Pick the file format from the dropdown
4

Preview changes

Review what will be imported, including any errors or warnings
5

Confirm import

Confirm to execute the import operation

​
Exporting Data

1

Access export

Click the “Export” button on the changelist page
2

Select format

Choose your preferred export format
3

Select fields (optional)

If using SelectableFieldsExportForm, choose which fields to include
4

Download

Click export to download your file
Import Export Workflow

​
Performance Optimization

​
Bulk Operations

Optimize import performance for large datasets:
resources.py
class BookResource(resources.ModelResource):
    class Meta:
        model = Book
        batch_size = 1000  # Import in batches
        use_bulk = True    # Use bulk_create/bulk_update

​
Deferred Fields

Exclude heavy fields from export:
resources.py
class BookResource(resources.ModelResource):
    class Meta:
        model = Book
        exclude = ["cover_image", "full_text"]  # Skip large fields

​
Example CSV Format

id,title,author_name,published_date,isbn
1,"Django for Beginners","William Vincent","2023-01-15","9781735467221"
2,"Two Scoops of Django","Daniel Roy Greenfeld","2022-06-01","9781081582162"
3,"Django Design Patterns","Arun Ravindran","2023-03-20","9781484282281"

​
Live Demo

Try Import/Export Features

Explore data import and export functionality with real examples

​
Common Use Cases

Transfer data between environments or systems:
# Export from production
# Import to staging with same format
# Validate before deploying
Update multiple records via spreadsheet:
# Export current data
# Edit in Excel/Google Sheets
# Import to update records
Regular exports for backup purposes:
# Scheduled exports via management command
# Store in S3 or backup location
Export for analysis in external tools:
# Export to CSV/Excel
# Analyze in pandas, R, or Excel
# Import updated data if needed

​
Resources

Import-Export Docs

Official documentation and tutorials

GitHub Repository

Source code and examples
Always test imports on a copy of your data first to prevent accidental overwrites or data loss.

Build docs developers (and LLMs) love

Get started for freeTalk to us