Developer Interface

Forms and Fields

class flask_wtf.FlaskForm(formdata=<object object>, **kwargs)

Flask-specific subclass of WTForms Form.

If formdata is not specified, this will use flask.request.form and flask.request.files. Explicitly pass formdata=None to prevent this.


Render the form's hidden fields in one call.

A field is considered hidden if it uses the HiddenInput widget.

If fields are given, only render the given fields that are hidden. If a string is passed, render the field with that name if it exists.

Changed in version 0.13: No longer wraps inputs in hidden div. This is valid HTML 5.

Changed in version 0.13: Skip passed fields that aren't hidden. Skip passed names that don't exist.


Consider the form submitted if there is an active request and the method is POST, PUT, PATCH, or DELETE.


Call validate() only if the form is submitted. This is a shortcut for form.is_submitted() and form.validate().

class flask_wtf.Form(...)

Deprecated since version 0.13: Renamed to FlaskForm.

class flask_wtf.RecaptchaField(label='', validators=None, **kwargs)
class flask_wtf.Recaptcha(message=None)

Validates a ReCaptcha.

class flask_wtf.RecaptchaWidget
class flask_wtf.file.FileField(label=None, validators=None, filters=(), description='', id=None, default=None, widget=None, render_kw=None, _form=None, _name=None, _prefix='', _translations=None, _meta=None)

Werkzeug-aware subclass of wtforms.fields.FileField.


Return True if is a FileStorage object.

Deprecated since version 0.14.1: data is no longer set if the input is not a non-empty FileStorage. Check is not None instead.

class flask_wtf.file.FileAllowed(upload_set, message=None)

Validates that the uploaded file is allowed by a given list of extensions or a Flask-Uploads UploadSet.

  • upload_set -- A list of extensions or an UploadSet
  • message -- error message

You can also use the synonym file_allowed.

class flask_wtf.file.FileRequired(message=None)

Validates that the data is a Werkzeug FileStorage object.

Parameters:message -- error message

You can also use the synonym file_required.

CSRF Protection

class flask_wtf.csrf.CSRFProtect(app=None)

Enable CSRF protection globally for a Flask app.

app = Flask(__name__)
csrf = CsrfProtect(app)

Checks the csrf_token field sent with forms, or the X-CSRFToken header sent with JavaScript requests. Render the token in templates using {{ csrf_token() }}.

See the CSRF Protection documentation.


Register a function that will generate the response for CSRF errors.

Deprecated since version 0.14: Use the standard Flask error system with @app.errorhandler(CSRFError) instead. This will be removed in version 1.0.

The function will be passed one argument, reason. By default it will raise a CSRFError.

def csrf_error(reason):
    return render_template('error.html', reason=reason)

Due to historical reasons, the function may either return a response or raise an exception with flask.abort().


Mark a view or blueprint to be excluded from CSRF protection.

@app.route('/some-view', methods=['POST'])
def some_view():
bp = Blueprint(...)
class flask_wtf.csrf.CsrfProtect(...)

Deprecated since version 0.14: Renamed to CSRFProtect.

class flask_wtf.csrf.CSRFError(description=None, response=None)

Raise if the client sends invalid CSRF data with the request.

Generates a 400 Bad Request response with the failure reason by default. Customize the response by registering a handler with flask.Flask.errorhandler().

flask_wtf.csrf.generate_csrf(secret_key=None, token_key=None)

Generate a CSRF token. The token is cached for a request, so multiple calls to this function will generate the same token.

During testing, it might be useful to access the signed token in g.csrf_token and the raw token in session['csrf_token'].

  • secret_key -- Used to securely sign the token. Default is WTF_CSRF_SECRET_KEY or SECRET_KEY.
  • token_key -- Key where token is stored in session for comparision. Default is WTF_CSRF_FIELD_NAME or 'csrf_token'.
flask_wtf.csrf.validate_csrf(data, secret_key=None, time_limit=None, token_key=None)

Check if the given data is a valid CSRF token. This compares the given signed token to the one stored in the session.

  • data -- The signed CSRF token to be checked.
  • secret_key -- Used to securely sign the token. Default is WTF_CSRF_SECRET_KEY or SECRET_KEY.
  • time_limit -- Number of seconds that the token is valid. Default is WTF_CSRF_TIME_LIMIT or 3600 seconds (60 minutes).
  • token_key -- Key where token is stored in session for comparision. Default is WTF_CSRF_FIELD_NAME or 'csrf_token'.

ValidationError -- Contains the reason that validation failed.

Changed in version 0.14: Raises ValidationError with a specific error message rather than returning True or False.