django-multiselectfield provides new model and form fields for Django, allowing users to select multiple options from a predefined list. The selected values are stored in the database as a CharField containing comma-separated values. The current version is 1.0.1, and the project has an irregular release cadence, with a significant 1.0.0 release in June 2025 that introduced breaking changes.
pip install django-multiselectfieldVerified import paths — ran on the pinned version, not inferred.
To use `MultiSelectField`, define your choices as a tuple of tuples. Add `multiselectfield` to your `INSTALLED_APPS` and then define a model field using `MultiSelectField`. Remember to run `makemigrations` and `migrate`.
Remove any references to `MSFList` or `MSFFlatchoices` from your code. If you were using them for `list_display`, consider using `get_FOO_display` method on your model or a custom admin method.
Ensure all choices provided to `MultiSelectField` are string-based. For example, use `(('1', 'Item 1'), ('2', 'Item 2'))` instead of `((1, 'Item 1'), (2, 'Item 2'))`.Use a custom method on your `ModelAdmin` or the `get_FOO_display` method on your model to format the output for `list_display`. Example: `list_display = ('get_my_field_display',)` in `ModelAdmin` where `get_my_field_display` is a method on the model.Ensure jQuery and jQuery UI are loaded in your templates when using `SortMultiSelectField` outside of the default Django admin forms. In the admin, you might need to explicitly include them in your `ModelAdmin`'s `form` definition or `change_form.html`.
Use `blank=True, default=''` instead of `null=True` for `MultiSelectField` if the field is optional.
Ensure that the choices defined for `MultiSelectField` in your model use string keys, even if they represent numerical values, or explicitly convert the incoming string values to integers before validation if integer choices are strictly necessary and handled correctly throughout the application. For example, use `(('1', 'Item 1'), ('2', 'Item 2'))` instead of `((1, 'Item 1'), (2, 'Item 2'))` in your `MY_CHOICES` tuple.Ensure that the choices provided to the `MultiSelectField` in your form or model match the values being submitted. If using dynamic choices, update the `choices` attribute of the field in the form's `__init__` method, or verify that the selected values are being passed as a list of valid keys.
Identify where the object becomes a list instead of a string. If you need to process individual items, iterate over the list directly. If you expect a string, ensure that the data type is indeed a string before calling `split()` (e.g., by converting it back to a string with `','.join(my_list)` if it was a list of items to be split).
Update to a version of `django-multiselectfield` that officially supports Django 5.0+. If an updated version is not available, a common workaround involves commenting out the problematic `_get_flatchoices` property definition in the `multiselectfield/db/fields.py` file, as the functionality is directly provided by Django 5.0+.