398

The documentation says that CharField() should be used for smaller strings and TextField() should be used for larger strings.

Okay, but where is the line drawn between "small" and "large"? What's going on under the hood here that makes this the case?

5 Answers 5

466

It's a difference between RDBMS's varchar (or similar) — those are usually specified with a maximum length, and might be more efficient in terms of performance or storage — and text (or similar) types — those are usually limited only by hardcoded implementation limits (not a DB schema).

PostgreSQL 9, specifically, states that "There is no performance difference among these three types", but AFAIK there are some differences in e.g. MySQL, so this is something to keep in mind.

A good rule of thumb is that you use CharField when you need to limit the maximum length, TextField otherwise.

This is not really Django-specific, also.

5
  • 50
    And conversely, if you use CharField then you must have a maximum length Jan 8, 2014 at 3:34
  • 22
    I've found that using TextField by default can impact the portability of your app. There might not be a performance hit on Postgres, but Oracle will store it as a CLOB which has some annoyances, like not being able to use the field in WHERE statements. Just something to consider.
    – serverpunk
    Jul 10, 2015 at 20:00
  • 7
    One should also consider that in Oracle CharField can't have max_length greater than 2000, or it issues an ORA-00910: specified length too long for its datatype error.
    – Dinei
    Feb 8, 2017 at 13:21
  • Useful to note, when considering field attributes, that Postgres docs also say (emphasis mine): "the longest possible character string that can be stored is about 1 GB. (The maximum value that will be allowed for n in the data type declaration is less than that [...] If you desire to store long strings with no specific upper limit, use text or character varying without a length specifier, rather than making up an arbitrary length limit.)"
    – iff_or
    Apr 3, 2018 at 20:27
  • 5
    I believe the really important difference between the two in django is how a view will handle the field. In a generic edit view the TextField will render as a multi-line re-sizable input; whilst the CharField is a single line input. I haven't looked at the django source for TextField, but I'm going to assume if any generated html is attached to a TextField, then it will most likely implement a way to properly manipulate multline text. Jul 12, 2018 at 13:16
48

In some cases it is tied to how the field is used. In some DB engines the field differences determine how (and if) you search for text in the field. CharFields are typically used for things that are searchable, like if you want to search for "one" in the string "one plus two". Since the strings are shorter they are less time consuming for the engine to search through. TextFields are typically not meant to be searched through (like maybe the body of a blog) but are meant to hold large chunks of text. Now most of this depends on the DB Engine and like in Postgres it does not matter.

Even if it does not matter, if you use ModelForms you get a different type of editing field in the form. The ModelForm will generate an HTML form the size of one line of text for a CharField and multiline for a TextField.

1
  • 4
    This is by far the best explanation because it mentions how it generates the field in a form. The Charfield will just be a one line input, but the TextField will be a resizable multiline. TextField makes sense when you primarily implement generic class views. It works great for a description field or the like. I also like how renderbox mentioned that you wouldn't want to use it for any filters/searches. Jul 12, 2018 at 13:10
17

CharField has max_length of 255 characters while TextField can hold more than 255 characters. Use TextField when you have a large string as input. It is good to know that when the max_length parameter is passed into a TextField it passes the length validation to the TextArea widget.

1
  • 2
    "Any fields that are stored with VARCHAR column types have their max_length restricted to 255 characters if you are using unique=True for the field." (My emphasis.)
    – l0b0
    Apr 29, 2020 at 21:46
15

For eg.,. 2 fields are added in a model like below..

description = models.TextField(blank=True, null=True)
title = models.CharField(max_length=64, blank=True, null=True)

Below are the mysql queries executed when migrations are applied.


for TextField(description) the field is defined as a longtext

ALTER TABLE `sometable_sometable` ADD COLUMN `description` longtext NULL;

The maximum length of TextField of MySQL is 4GB according to string-type-overview.


for CharField(title) the max_length(required) is defined as varchar(64)

ALTER TABLE `sometable_sometable` ADD COLUMN `title` varchar(64) NULL;
ALTER TABLE `sometable_sometable` ALTER COLUMN `title` DROP DEFAULT;
1
5

TextField can contain more than 255 characters, but CharField is used to store shorter length of strings.

When you want to store long text, use TextField, or when you want shorter strings then CharField is useful.

  article_title = models.CharField(max_length=150)
  article_body = models.TextField()
1
  • This "answer" states the context of the question, it doesn't provide an answer about "when/why" Oct 15, 2022 at 11:54

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.