---

name: django-import-export description: Use when working with django-import-export

Django-Import-Export Skill

Use when working with django-import-export, generated from official documentation.

When to Use This Skill

This skill should be triggered when:

• Working with django-import-export
• Asking about django-import-export features or APIs
• Implementing django-import-export solutions
• Debugging django-import-export code
• Learning django-import-export best practices

Quick Reference

Common Patterns

Pattern 1: Frequently Asked Questions What’s the best way to communicate a problem, question, or suggestion? To submit a feature, to report a bug, or to ask a question, please refer our contributing guidelines. How can I help? We welcome contributions from the community. You can help in the following ways: Reporting bugs or issues. Answering questions which arise on Stack Overflow or as Github issues. Providing translations for UI text. Suggesting features or changes. We encourage you to read the contributing guidelines. Common issues import_id_fields error on import The following error message can be seen on import: The following fields are declared in ‘import_id_fields’ but are not present in the resource This indicates that the Resource has not been configured correctly, and the import logic fails. Specifically, the import process is attempting to use either the defined or default values for import_id_fields and no matching field has been detected in the resource fields. See Create or update model instances. In cases where you are deliberately using generated fields in import_id_fields and these fields are not present in the dataset, then you need to modify the resource definition to accommodate this. See Using ‘dynamic fields’ to identify existing instances. How to handle double-save from Signals This issue can apply if you have implemented post-save Signals, and you are using the import workflow in the Admin interface. You will find that the post-save signal is called twice for each instance. The reason for this is that the model save() method is called twice: once for the ‘confirm’ step and once for the ‘import’ step. The call to save() during the ‘confirm’ step is necessary to prove that the object will be saved successfully, or to report any exceptions in the Admin UI if save failed. After the ‘confirm’ step, the database transaction is rolled back so that no changes are persisted. Therefore there is no way at present to stop save() being called twice, and there will always be two signal calls. There is a workaround, which is to set a temporary flag on the instance being saved: class BookResource(resources.ModelResource): def before_save_instance(self, instance, row, **kwargs): # during 'confirm' step, dry_run is True instance.dry_run = kwargs.get("dry_run", False) class Meta: model = Book fields = ('id', 'name') Your signal receiver can then include conditional logic to handle this flag: @receiver(post_save, sender=Book) def my_callback(sender, **kwargs): instance = kwargs["instance"] if getattr(instance, "dry_run"): # no-op if this is the 'confirm' step return else: # your custom logic here # this will be executed only on the 'import' step pass Further discussion here and here. How to dynamically set resource values There can be use cases where you need a runtime or user supplied value to be passed to a Resource. See How to dynamically set resource values. How to set a value on all imported instances prior to persisting If you need to set the same value on each instance created during import then refer to How to set a value on all imported instances prior to persisting. How to export from more than one table In the usual configuration, a Resource maps to a single model. If you want to export data associated with relations to that model, then these values can be defined in the fields declaration. See Model relations. How to import imagefield in excel cell Please refer to this issue. How to hide stack trace in UI error messages Please refer to How to format UI error messages. Ids incremented twice during import When importing using the Admin site, it can be that the ids of the imported instances are different from those show in the preview step. This occurs because the rows are imported during ‘confirm’, and then the transaction is rolled back prior to the confirm step. Database implementations mean that sequence numbers may not be reused. Consider enabling IMPORT_EXPORT_SKIP_ADMIN_CONFIRM as a workaround. See this issue for more detailed discussion. Not Null constraint fails when importing blank CharField This was an issue in v3 which is resolved in v4. The issue arises when importing from Excel because empty cells are converted to None during import. If the import process attempted to save a null value then a ‘NOT NULL’ exception was raised. In v4, initialization checks to see if the Django CharField has blank set to True. If it does, then null values or empty strings are persisted as empty strings. If it is necessary to persist None instead of an empty string, then the allow_blank widget parameter can be set: class BookResource(resources.ModelResource): name = Field(widget=CharWidget(allow_blank=False)) class Meta: model = Book See this issue. Foreign key is null when importing It is possible to reference model relations by defining a field with the double underscore syntax. For example: class BookResource(ModelResource): class Meta: model = Book fields = ("author__name",) This means that during export, the relation will be followed and the referenced field will be added correctly to the export. It works the same way when using attribute in Field. For example: class BookResource(ModelResource): author_name = Field(attribute="author__name") class Meta: model = Book fields = ("author_name",) This does not work during import because the reference may not be enough to identify the correct relation instance. ForeignKeyWidget should be used during import. See the documentation explaining Foreign Key relations. How to customize export data See the following responses on StackOverflow: https://stackoverflow.com/a/55046474/39296 https://stackoverflow.com/questions/74802453/export-only-the-data-registered-by-the-user-django-import-export How to customize Excel export data If you want more control over how export data is formatted when exporting to Excel you can write a custom format which uses the openpyxl API. See the example here. How to set export file encoding If export produces garbled or unexpected output, you may need to set the export encoding. See this issue. How to create relation during import if it does not exist See Creating non-existent relations. How to handle large file imports If uploading large files, you may encounter time-outs. See Using celery and Bulk imports. Performance issues or unexpected behavior during import This could be due to hidden rows in Excel files. Hidden rows can be excluded using IMPORT_EXPORT_IMPORT_IGNORE_BLANK_LINES. Refer to this PR for more information. How to use field other than id in Foreign Key lookup See Foreign Key relations. RelatedObjectDoesNotExist exception during import This can occur if a model defines a str() method which references a primary key or foreign key relation, and which is None during import. There is a workaround to deal with this issue. Refer to this comment. ‘failed to assign change_list_template attribute’ warning in logs This indicates that the change_list_template attribute could not be set, most likely due to a clash with a third party library. Refer to Interoperability with 3rd party libraries. How to skip rows with validation errors during import Refer to this comment. FileNotFoundError during Admin import ‘confirm’ step You may receive an error during import such as: FileNotFoundError [Errno 2] No such file or directory: '/tmp/tmp5abcdef' This usually happens because you are running the Admin site in a multi server or container environment. During import, the import file has to be stored temporarily and then retrieved for storage after confirmation. Therefore FileNotFoundError error can occur because the temp storage is not available to the server process after confirmation. To resolve this, you should avoid using temporary file system storage in multi server environments. Refer to Import confirmation for more information. How to export large datasets Large datasets can be exported in a number of ways, depending on data size and preferences. You can write custom scripts or Admin commands to handle the export. Output can be written to a local filesystem, cloud bucket, network storage etc. Refer to the documentation on exporting programmatically. You can use the third party library django-import-export-celery to handle long-running exports. You can enable export via admin action and then select items for export page by page in the Admin UI. This will work if you have a relatively small number of pages and can handle export to multiple files. This method is suitable as a one-off or as a simple way to export large datasets via the Admin UI. How to change column names on export If you want to modify the names of the columns on export, you can do so by overriding get_export_headers(): class BookResource(ModelResource): def get_export_headers(self, fields=None): headers = super().get_export_headers(fields=fields) for i, h in enumerate(headers): if h == 'name': headers[i] = "NEW COLUMN NAME" return headers class Meta: model = Book How to configure logging Refer to logging configuration for more information. Export to Excel gives IllegalCharacterError This occurs when your data contains a character which cannot be rendered in Excel. You can configure import-export to sanitize these characters.

Copyimport_id_fields

Pattern 2: It is possible to reference model relations by defining a field with the double underscore syntax. For example:

Copyclass BookResource(ModelResource):

    class Meta:
        model = Book
        fields = ("author__name",)

Pattern 3: It works the same way when using attribute in Field. For example:

Copyattribute

Pattern 4: Release Notes v5.0 Breaking changes This release fixes an issue with form field name clashes (see 2108). If you have any customizations which rely on form field names then you may need to make some adjustments as a result of this change. The resource, format and export_items field names are now prepended with django-import-export-. Removed the deprecated get_valid_export_item_pks() method in favour of get_queryset(). Use the ModelAdmin’s get_queryset() or get_export_queryset() instead. See PR 1890. Fixed issue where export forms were incorrectly showing import fields instead of export fields. This was resolved by introducing context-specific methods for field retrieval. See deprecations and PR 2118. Deprecations The get_user_visible_fields() method is now deprecated and will be removed in version 6.0. Use get_user_visible_import_fields() for import contexts and get_user_visible_export_fields() for export contexts instead. This change ensures that import and export operations show their respective field sets correctly in admin forms. v4.2 When exporting via admin action, the queryset is now filtered on get_queryset() instead of the Model’s default queryset. This should have no impact on existing implementations. This change also made get_valid_export_item_pks() obsolete, as the ModelAdmin’s get_export_queryset(), or ModelAdmin’s get_queryset can be used instead. The get_valid_export_item_pks() method is now deprecated. See PR 1890. Removed internal method _get_enabled_export_fields() in favour of passing the selected fields list as a new parameter to export_resource() and get_export_headers(). Hide the “Resource” form when it only has one option, to avoid potentially confusing text in the interface like “Resource: BookResource”. To undo this change, use a form subclass that changes the field’s widget to a django.forms.Select. See 1908 tablib has been upgraded from v3.5.0 to 3.6.1. This upgrade removes tablib’s dependency on MarkupPy in favour of ElementTree. If you export to HTML, then this change may affect your output format, particularly if you have already escaped HTML characters in the text. See issue 1627. Breaking changes This release fixes a regression introduced in v4. From v4.2, numeric, boolean and date/time widgets are written as native values to spreadsheet formats (ODS, XLS, XLSX). This was the default behavior in v3. See documentation. This means that the coerce_to_string value which is passed to Widget is now ignored if you are exporting to a spreadsheet format from the Admin interface. If you have subclassed Widget, Field or Resource, then you may need to adjust your code to include the **kwargs param as follows: Previous New Widget.render(self, value, obj=None) Widget.render(self, value, obj=None, **kwargs) Field.export(self, instance) Field.export(self, instance, **kwargs) Resource.export_field(self, field, instance) Resource.export_field(self, field, instance, **kwargs) Resource.export_resource(self, instance, selected_fields=None) Resource.export_resource(self, instance, selected_fields=None, **kwargs) v4.1 The Resource.get_fields() method is no longer called within the package and has been deprecated. If you have overridden this method then it should be removed. v4.0 v4 introduces significant updates to import-export. We have taken the opportunity to introduce breaking changes in order to fix some long-standing issues. Refer to the changelog for more information. Please ensure you test thoroughly before deploying v4 to production. This guide describes the major changes and how to upgrade. Installation We have modified installation methods to allow for optional dependencies. This means that you have to explicitly declare dependencies when installing import-export. If you are not sure, or want to preserve the pre-v4 behaviour, then ensure that import-export is installed as follows (either in your requirements file or during installation): django-import-export[all] Functional changes CharWidget Constructor arguments are dynamically set during instantiation based on the properties of the underlying Django db CharField. If the db field has blank set to True, then incoming values of empty strings or null are stored as empty strings. See CharWidget. clean() will now return a string type as the default. The coerce_to_string option introduced in v3 is no longer used in this method. Validation error messages The following widgets have had validation error messages updated: DateWidget TimeWidget DateTimeWidget DurationWidget Export format We have standardized the export output which is returned from render(). Prior to v4, the export format returned from render() varied between Widget implementations. In v4, return values are rendered as strings by default (where applicable), with None values returned as empty strings. Widget params can modify this behavior. This causes a change when exporting to Excel. In v3, certain fields, such as numeric values, were rendered as their native type. In v4, all fields are now rendered as strings. To preserve the v3 behavior when exporting to Excel, set the coerce_to_string param to False. See documentation. Widget API documentation. Export field order The ordering rules for exported fields has been standardized. See documentation. Error output If the raise_errors parameter of import_data() is True, then an instance of ImportError is raised. This exception wraps the underlying exception. See this PR. Check import_id_fields Prior to v4 we had numerous issues where users were confused when imports failed due to declared import_id_fields not being present in the dataset. We added functionality in v4 to check for this and to raise a clearer error message. In some use-cases, it is a requirement that import_id_fields are not in the dataset, and are generated dynamically. If this affects your implementation, start with the documentation here. Deprecations The obj param passed to render() is deprecated. The render() method should not need to have a reference to model instance. The call to render() from export() has been removed. Use of ExportViewFormMixin is deprecated. See this issue. See Renamed methods. In the Admin UI, the declaration of resource_class is replaced by resource_classes: class BookAdmin(ImportExportModelAdmin): # remove this line # resource_class = BookResource # replace with this resource_classes = [BookResource] Admin UI LogEntry LogEntry instances are created during import for creates, updates and deletes. The functionality to store LogEntry has changed in v4 in order to address a deprecation in Django 5. For this to work correctly, deleted instances are now always copied and retained in each RowResult so that they can be recorded in each LogEntry. This only occurs for delete operations initiated from the Admin UI. Export action The export action has been updated to include the export workflow. Prior to v4, it was possible to select export selected items using an export admin action. However this meant that the export workflow was skipped and it was not possible to select the export resource. This has been fixed in v4 so that export workflow is now present when exporting via the Admin UI action. For more information see export documentation. Export selected fields The export ‘confirm’ page now includes selectable fields for export. If you wish to revert to the previous (v3) version of the export confirm screen, add a export_form_class declaration to your Admin class subclass, for example: class BookAdmin(ImportExportModelAdmin): export_form_class = ExportForm Success message The success message shown on successful import has been updated to include the number of ‘deleted’ and ‘skipped’ rows. See this PR. Import error messages The default error message for import errors has been modified to simplify the format. Error messages now contain the error message only by default. The row and traceback are not presented. The original format can be restored by setting import_error_display on the Admin class definition. For example: class BookAdmin(ImportExportModelAdmin): import_error_display = ("message", "row", "traceback") See this issue. API changes v4 of import-export contains a number of changes to the API. These changes are summarized in the table below. Refer to this PR for detailed information. If you have customized import-export by overriding methods, then you may have to modify your installation before working with v4. If you have not overridden any methods then you should not be affected by these changes and no changes to your code should be necessary. The API changes include changes to method arguments, although some method names have changed. Methods which process row data have been updated so that method args are standardized. This has been done to resolve inconsistency issues where the parameters differed between method calls, and to allow easier extensibility. import_export.resources.Resource Renamed methods Previous New Summary import_obj(self, obj, data, dry_run, **kwargs) import_instance(self, instance, row, **kwargs) obj param renamed to instance data param renamed to row dry_run param now in kwargs after_import_instance(self, instance, new, row_number=None, **kwargs) after_init_instance(self, instance, new, row, **kwargs) row added as mandatory arg row_number now in kwargs Parameter changes This section describes methods in which the parameters have changed. Previous New Summary before_import(self, dataset, using_transactions, dry_run, **kwargs) before_import(self, dataset, **kwargs) using_transactions param now in kwargs dry_run param now in kwargs after_import(self, dataset, result, using_transactions, dry_run, **kwargs) after_import(self, dataset, result, **kwargs) using_transactions param now in kwargs dry_run param now in kwargs before_import_row(self, row, row_number=None, **kwargs) before_import_row(self, row, **kwargs) row_number now in kwargs after_import_row(self, row, row_result, row_number=None, **kwargs) after_import_row(self, row, row_result, **kwargs) row_number now in kwargs import_row(self, row, instance_loader, using_transactions=True, dry_run=False, **kwargs) import_row(self, row, instance_loader, **kwargs) dry_run param now in kwargs using_transactions param now in kwargs save_instance(self, instance, is_create, using_transactions=True, dry_run=False) save_instance(self, instance, is_create, row, **kwargs) dry_run param now in kwargs using_transactions param now in kwargs row added as mandatory arg save_m2m(self, obj, data, using_transactions, dry_run) save_m2m(self, instance, row, **kwargs) row added as mandatory arg obj renamed to instance data renamed to row dry_run param now in kwargs using_transactions param now in kwargs before_save_instance(self, instance, using_transactions, dry_run) before_save_instance(self, instance, row, **kwargs) row added as mandatory arg dry_run param now in kwargs using_transactions param now in kwargs after_save_instance(self, instance, using_transactions, dry_run) after_save_instance(self, instance, row, **kwargs) row added as mandatory arg dry_run param now in kwargs using_transactions param now in kwargs delete_instance(self, instance, using_transactions=True, dry_run=False) delete_instance(self, instance, row, **kwargs) row added as mandatory arg dry_run param now in kwargs using_transactions param now in kwargs before_delete_instance(self, instance, dry_run) before_delete_instance(self, instance, row, **kwargs) row added as mandatory arg dry_run param now in kwargs using_transactions param now in kwargs after_delete_instance(self, instance, dry_run) after_delete_instance(self, instance, row, **kwargs) row added as mandatory arg dry_run param now in kwargs using_transactions param now in kwargs import_field(self, field, obj, data, is_m2m=False, **kwargs) import_field(self, field, instance, row, is_m2m=False, **kwargs): obj renamed to instance data renamed to row before_export(self, queryset, *args, **kwargs) before_export(self, queryset, **kwargs) unused *args list removed after_export(self, queryset, data, *args, **kwargs) after_export(self, queryset, dataset, **kwargs) unused *args list removed data renamed to dataset filter_export(self, queryset, *args, **kwargs) filter_export(self, queryset, **kwargs) unused *args list removed export_field(self, field, obj) export_field(self, field, instance) obj renamed to instance export_resource(self, obj) export_resource(self, instance, fields=None) obj renamed to instance fields passed as kwarg export(self, *args, queryset=None, **kwargs) export(self, queryset=None, **kwargs) unused *args list removed get_export_headers(self) get_export_headers(self, fields=None) fields passed as kwarg import_export.mixins.BaseImportExportMixin Parameter changes Previous New Summary get_resource_classes(self) get_resource_classes(self, request) Added request param get_resource_kwargs(self, request, *args, **kwargs) get_resource_kwargs(self, request, **kwargs) unused *args list removed import_export.mixins.BaseImportMixin Parameter changes Previous New Summary get_import_resource_kwargs(self, request, *args, **kwargs) get_import_resource_kwargs(self, request, **kwargs) unused *args list removed get_import_resource_classes(self) get_import_resource_classes(self, request) Added request param choose_import_resource_class(self, form) choose_import_resource_class(self, form, request) Added request param import_export.mixins.BaseExportMixin Parameter changes Previous New Summary get_export_resource_classes(self) get_export_resource_classes(self, request) Added request param get_export_resource_kwargs(self, request, *args, **kwargs) get_export_resource_kwargs(self, request, **kwargs) unused *args list removed get_data_for_export(self, request, queryset, *args, **kwargs) get_data_for_export(self, request, queryset, **kwargs) unused *args list removed choose_export_resource_class(self, form) choose_export_resource_class(self, form, request) Added request param import_export.fields.Field Parameter changes Previous New Summary clean(self, data, **kwargs) clean(self, row, **kwargs) data renamed to row get_value(self, instance) get_value(self, obj) obj renamed to instance save(self, obj, data, is_m2m=False, **kwargs) save(self, instance, row, is_m2m=False, **kwargs) obj renamed to instance data renamed to row export(self, obj) export(self, instance) obj renamed to instance import_export.forms.ImportExportFormBase If you have subclassed one of the forms then you may need to modify the parameters passed to constructors. The input_format field of ImportForm has been moved to the parent class (ImportExportFormBase) and renamed to format. The file_format field of ExportForm has been removed and is now replaced by format. Parameter changes Previous New Summary init(self, *args, resources=None, **kwargs) init(self, formats, resources, **kwargs) formats added as a mandatory arg resources added as a mandatory arg unused *args list removed

Copyresource

Pattern 5: The export ‘confirm’ page now includes selectable fields for export. If you wish to revert to the previous (v3) version of the export confirm screen, add a export_form_class declaration to your Admin class subclass, for example:

Copyexport_form_class

Pattern 6: The original format can be restored by setting import_error_display on the Admin class definition. For example:

Copyimport_error_display

Pattern 7: Django Management Commands Export Command The export command allows you to export data from a specified Django model or a resource class. The exported data can be saved in different formats, such as CSV or XLSX. Usage python manage.py export [--encoding ENCODING] format: Specify the format in which the data should be exported. - resource: Specify the resource or model to export. Accepts a resource class or a model class in dotted path format. - –encoding (optional): Specify the encoding (e.g., ‘utf-8’) to be used for the exported data. Example python manage.py export CSV auth.User This command will export the User model data in CSV format using utf-8 encoding. Another example: python manage.py export XLSX mymodule.resources.MyResource This command will export the data from MyResource resource in XLSX format. Import Command The import command allows you to import data from a file using a specified Django model or a custom resource class. Usage python manage.py import <import_file_name> [--format FORMAT] [--encoding ENCODING] [--dry-run] [--raise-errors] resource: The resource class or model class in dotted path format. import_file_name: The file from which data is imported (- can be used to indicate stdin). –format (optional): Specify the format of the data to import. If not provided, it will be guessed from the mimetype. –encoding (optional): Specify the character encoding of the data. –dry-run: Perform a trial run without making changes. –raise-errors: Raise any encountered errors during execution. Example Import data from file into auth.User model using default model resource: python manage.py import auth.User users.csv Import data from file using custom model resource, raising errors: python manage.py import --raise-errors helper.MyUserResource users.csv

Copyexport

Pattern 8: Another example:

Copypython manage.py export XLSX mymodule.resources.MyResource

Reference Files

This skill includes comprehensive documentation in references/:

• _images.md - Images documentation
• _sources.md - Sources documentation
• api.md - Api documentation
• other.md - Other documentation

Use view to read specific reference files when detailed information is needed.

Working with This Skill

For Beginners

Start with the getting_started or tutorials reference files for foundational concepts.

For Specific Features

Use the appropriate category reference file (api, guides, etc.) for detailed information.

For Code Examples

The quick reference section above contains common patterns extracted from the official docs.

Resources

references/

Organized documentation extracted from official sources. These files contain:

• Detailed explanations
• Code examples with language annotations
• Links to original documentation
• Table of contents for quick navigation

scripts/

Add helper scripts here for common automation tasks.

assets/

Add templates, boilerplate, or example projects here.

Notes

• This skill was automatically generated from official documentation
• Reference files preserve the structure and examples from source docs
• Code examples include language detection for better syntax highlighting
• Quick reference patterns are extracted from common usage examples in the docs

Updating

To refresh this skill with updated documentation:

1. Re-run the scraper with the same configuration
2. The skill will be rebuilt with the latest information