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 importidfields error on import The following error message can be seen on import: The following fields are declared in ‘importidfields’ 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 importidfields 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 importidfields 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 beforesaveinstance(self, instance, row, kwargs): # during 'confirm' step, dryrun is True instance.dryrun = kwargs.get("dryrun", False) class Meta: model = Book fields = ('id', 'name') Your signal receiver can then include conditional logic to handle this flag: @receiver(postsave, sender=Book) def mycallback(sender, kwargs): instance = kwargs["instance"] if getattr(instance, "dryrun"): # 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 IMPORTEXPORTSKIPADMINCONFIRM 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 allowblank widget parameter can be set: class BookResource(resources.ModelResource): name = Field(widget=CharWidget(allowblank=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 = ("authorname",) 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 IMPORTEXPORTIMPORTIGNOREBLANKLINES. 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 changelisttemplate attribute’ warning in logs This indicates that the changelisttemplate 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 getexportheaders(): class BookResource(ModelResource): def getexportheaders(self, fields=None): headers = super().getexportheaders(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.

import_id_fields

Pattern 2: 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",)

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

attribute

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 exportitems field names are now prepended with django-import-export-. Removed the deprecated getvalidexportitempks() method in favour of getqueryset(). Use the ModelAdmin’s getqueryset() or getexportqueryset() 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 getuservisiblefields() method is now deprecated and will be removed in version 6.0. Use getuservisibleimportfields() for import contexts and getuservisibleexportfields() 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 getqueryset() instead of the Model’s default queryset. This should have no impact on existing implementations. This change also made getvalidexportitempks() obsolete, as the ModelAdmin’s getexportqueryset(), or ModelAdmin’s getqueryset can be used instead. The getvalidexportitempks() method is now deprecated. See PR 1890. Removed internal method getenabledexportfields() in favour of passing the selected fields list as a new parameter to exportresource() and getexportheaders(). 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 coercetostring 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.exportfield(self, field, instance) Resource.exportfield(self, field, instance, kwargs) Resource.exportresource(self, instance, selectedfields=None) Resource.exportresource(self, instance, selectedfields=None, kwargs) v4.1 The Resource.getfields() 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 coercetostring 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 coercetostring 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 raiseerrors parameter of importdata() is True, then an instance of ImportError is raised. This exception wraps the underlying exception. See this PR. Check importidfields Prior to v4 we had numerous issues where users were confused when imports failed due to declared importidfields 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 importidfields 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 resourceclass is replaced by resourceclasses: class BookAdmin(ImportExportModelAdmin): # remove this line # resourceclass = BookResource # replace with this resourceclasses = [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 exportformclass declaration to your Admin class subclass, for example: class BookAdmin(ImportExportModelAdmin): exportformclass = 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 importerrordisplay on the Admin class definition. For example: class BookAdmin(ImportExportModelAdmin): importerrordisplay = ("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. importexport.resources.Resource Renamed methods Previous New Summary importobj(self, obj, data, dryrun, kwargs) importinstance(self, instance, row, kwargs) obj param renamed to instance data param renamed to row dryrun param now in kwargs afterimportinstance(self, instance, new, rownumber=None, kwargs) afterinitinstance(self, instance, new, row, kwargs) row added as mandatory arg rownumber now in kwargs Parameter changes This section describes methods in which the parameters have changed. Previous New Summary beforeimport(self, dataset, usingtransactions, dryrun, kwargs) beforeimport(self, dataset, kwargs) usingtransactions param now in kwargs dryrun param now in kwargs afterimport(self, dataset, result, usingtransactions, dryrun, kwargs) afterimport(self, dataset, result, kwargs) usingtransactions param now in kwargs dryrun param now in kwargs beforeimportrow(self, row, rownumber=None, kwargs) beforeimportrow(self, row, kwargs) rownumber now in kwargs afterimportrow(self, row, rowresult, rownumber=None, kwargs) afterimportrow(self, row, rowresult, kwargs) rownumber now in kwargs importrow(self, row, instanceloader, usingtransactions=True, dryrun=False, kwargs) importrow(self, row, instanceloader, kwargs) dryrun param now in kwargs usingtransactions param now in kwargs saveinstance(self, instance, iscreate, usingtransactions=True, dryrun=False) saveinstance(self, instance, iscreate, row, kwargs) dryrun param now in kwargs usingtransactions param now in kwargs row added as mandatory arg savem2m(self, obj, data, usingtransactions, dryrun) savem2m(self, instance, row, kwargs) row added as mandatory arg obj renamed to instance data renamed to row dryrun param now in kwargs usingtransactions param now in kwargs beforesaveinstance(self, instance, usingtransactions, dryrun) beforesaveinstance(self, instance, row, kwargs) row added as mandatory arg dryrun param now in kwargs usingtransactions param now in kwargs aftersaveinstance(self, instance, usingtransactions, dryrun) aftersaveinstance(self, instance, row, kwargs) row added as mandatory arg dryrun param now in kwargs usingtransactions param now in kwargs deleteinstance(self, instance, usingtransactions=True, dryrun=False) deleteinstance(self, instance, row, kwargs) row added as mandatory arg dryrun param now in kwargs usingtransactions param now in kwargs beforedeleteinstance(self, instance, dryrun) beforedeleteinstance(self, instance, row, kwargs) row added as mandatory arg dryrun param now in kwargs usingtransactions param now in kwargs afterdeleteinstance(self, instance, dryrun) afterdeleteinstance(self, instance, row, kwargs) row added as mandatory arg dryrun param now in kwargs usingtransactions param now in kwargs importfield(self, field, obj, data, ism2m=False, kwargs) importfield(self, field, instance, row, ism2m=False, kwargs): obj renamed to instance data renamed to row beforeexport(self, queryset, args, kwargs) beforeexport(self, queryset, kwargs) unused args list removed afterexport(self, queryset, data, args, kwargs) afterexport(self, queryset, dataset, kwargs) unused args list removed data renamed to dataset filterexport(self, queryset, args, kwargs) filterexport(self, queryset, kwargs) unused args list removed exportfield(self, field, obj) exportfield(self, field, instance) obj renamed to instance exportresource(self, obj) exportresource(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 getexportheaders(self) getexportheaders(self, fields=None) fields passed as kwarg importexport.mixins.BaseImportExportMixin Parameter changes Previous New Summary getresourceclasses(self) getresourceclasses(self, request) Added request param getresourcekwargs(self, request, args, kwargs) getresourcekwargs(self, request, kwargs) unused args list removed importexport.mixins.BaseImportMixin Parameter changes Previous New Summary getimportresourcekwargs(self, request, args, kwargs) getimportresourcekwargs(self, request, kwargs) unused args list removed getimportresourceclasses(self) getimportresourceclasses(self, request) Added request param chooseimportresourceclass(self, form) chooseimportresourceclass(self, form, request) Added request param importexport.mixins.BaseExportMixin Parameter changes Previous New Summary getexportresourceclasses(self) getexportresourceclasses(self, request) Added request param getexportresourcekwargs(self, request, args, kwargs) getexportresourcekwargs(self, request, kwargs) unused args list removed getdataforexport(self, request, queryset, args, kwargs) getdataforexport(self, request, queryset, kwargs) unused args list removed chooseexportresourceclass(self, form) chooseexportresourceclass(self, form, request) Added request param importexport.fields.Field Parameter changes Previous New Summary clean(self, data, kwargs) clean(self, row, kwargs) data renamed to row getvalue(self, instance) getvalue(self, obj) obj renamed to instance save(self, obj, data, ism2m=False, kwargs) save(self, instance, row, ism2m=False, kwargs) obj renamed to instance data renamed to row export(self, obj) export(self, instance) obj renamed to instance importexport.forms.ImportExportFormBase If you have subclassed one of the forms then you may need to modify the parameters passed to constructors. The inputformat field of ImportForm has been moved to the parent class (ImportExportFormBase) and renamed to format. The fileformat 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

resource

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 exportformclass declaration to your Admin class subclass, for example:

export_form_class

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

import_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 <format> <resource> [--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 <resource> <importfilename> [--format FORMAT] [--encoding ENCODING] [--dry-run] [--raise-errors] resource: The resource class or model class in dotted path format. importfilename: 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

export

Pattern 8: Another example:

python 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