Skip to main content
Help improve PyPI by participating in a 5-minute user interface survey!

Fast CSV imports using django model forms.

Project Description

# django-model-import

[![PyPI version](](
[![Build Status](](

Django Model Import is a light weight CSV importer built for speed.

It uses a standard Django `ModelForm` to parse each row, giving you a familiar API to work with
for data validation and model instantiation. In most cases, if you already have a `ModelForm`
for the `ContentType` you are importing you do not need to create an import specific form.

To present feedback to the end-user running the import you can easily generate a preview
of the imported data by toggling the `commit` parameter.

It also provides some import optimized fields for ForeignKey's, allowing preloading all
possible values, or caching each lookup as it occurs, or looking up a model where multiple
fields are needed to uniquely identify a resource.

## Installation

Standard pip install:

pip install django-model-import

## Quickstart

import djangomodelimport

class BookImporter(djangomodelimport.ImporterModelForm):
name = forms.CharField()
author = CachedChoiceField(queryset=Author.objects.all(), to_field='name')

class Meta:
model = Book
fields = (

with'books.csv', 'rb') as fh:
data ="utf-8")

# Use tablib
parser = djangomodelimport.TablibCSVImportParser(BookImporter)
headers, rows = parser.parse(data)

# Process
importer = djangomodelimport.ModelImporter(BookImporter)
preview = importer.process(headers, rows, commit=False)
errors = preview.get_errors()

if errors:

importresult = importer.process(headers, rows, commit=True)
for result in importresult.get_results():

## Composite key lookups

Often a relationship cannot be referenced via a single unique string. For this we can use
a `CachedChoiceField` with a `CompositeLookupWidget`. The widget looks for the values
under the `type` and `variant` columns in the source CSV, and does a unique lookup
with the field names specified in `to_field`, e.g. `queryset.get(type__name=type, name=variant)`.

The results of each `get` are cached internally for the remainder of the import minimising
any database access.

class AssetImporter(ImporterModelForm):
site = djangomodelimport.CachedChoiceField(, to_field='ref')
type = djangomodelimport.CachedChoiceField(queryset=AssetType.objects.filter(is_active=True), to_field='name')
type_variant = djangomodelimport.CachedChoiceField(
widget=djangomodelimport.CompositeLookupWidget(source=('type', 'variant')),
to_field=('type__name', 'name'),
contractor = djangomodelimport.CachedChoiceField(, to_field='name')

## Flat related fields

Often you'll have a OneToOneField or just a ForeignKey to another model, but you want to be able to
create/update that other model via this one. You can flatten all of the related model's fields onto
this importer using `FlatRelatedField`.

class ClientImporter(ImporterModelForm):
primary_contact = FlatRelatedField(
'contact_name': {'to_field': 'name', 'required': True},
'email': {'to_field': 'email'},
'email_cc': {'to_field': 'email_cc'},
'mobile': {'to_field': 'mobile'},
'phone_bh': {'to_field': 'phone_bh'},
'phone_ah': {'to_field': 'phone_ah'},
'fax': {'to_field': 'fax'},

class Meta:
model = Client
fields = (


## Tests
Run tests with `python example/ test testapp`

Release history Release notifications

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
django-model-import-0.3.2.tar.gz (12.3 kB) Copy SHA256 hash SHA256 Source None Mar 1, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page