html — escaping and unescaping character data

html.escape and html.unescape, including the quote argument, and why escape is not a general HTML or JavaScript sanitizer, checked on Python 3.13.12.

モジュールページの本文は現在英語です。

The html module provides helpers for converting a few special characters to HTML character references and back. The module name is html; this page lives at /references/python/html/ and is not the HTML language tutorial at /references/html/.

html.escape(s, quote=True) replaces &, <, and >, and when quote is true it also replaces " and '. That is character escaping, not HTML parsing and not a sanitizer for arbitrary markup or scripts. It will not detect a javascript: URL, strip event-handler attributes, or validate a document. Official documentation describes these functions as conversions of special characters and character references, not as a security filter.

Examples were run against Python 3.13.12. They print strings only; no HTML is rendered and no script is executed.

Examples were checked against Python 3.13. See the official documentation for the complete API.

Python reference overview →

escape and unescape

escape always converts ampersand, less-than, and greater-than. With the default quote=True it also converts double and single quotes, which is useful when the result will be placed in an HTML attribute. quote=False leaves quotes unchanged.

unescape decodes HTML character references, including named HTML5 entities and numeric references. It is the inverse for the characters that escape produces, and it can also decode a broader set of entity names. It does not parse tags.

html.escape and html.unescape

html.escape(s, quote=True)
html.unescape(s)

escape converts &, <, >, and, by default, quotes. unescape decodes character references back to Unicode characters.

ParameterDescription
sA str to escape or unescape. Pass a string, not bytes.
quoteIf true (the default), also replace " with &quot; and ' with &#x27;. If false, quotes are left unchanged.

Returns: A new str. The original string is not modified.

  • In Python 3.13, a single quote is escaped as &#x27; when quote=True.
python
import html

sample = '<p class="note">A & B</p>'
print(html.escape(sample))
print(html.escape(sample, quote=False))
print(html.escape("it's ok"))
print(html.unescape('&lt;p class=&quot;note&quot;&gt;A &amp; B&lt;/p&gt;'))

Expected output

&lt;p class=&quot;note&quot;&gt;A &amp; B&lt;/p&gt;
&lt;p class="note"&gt;A &amp; B&lt;/p&gt;
it&#x27;s ok
<p class="note">A & B</p>

Related: HTML escape tool, HTML entity encoder, str methods

Official documentation →

escape is not a sanitizer

escape only replaces the characters listed above. A string that contains no &, <, >, ", or ' is returned unchanged, even if a later consumer might treat it as a URL or as script. A string that does contain tags is not cleaned: the brackets are escaped, but escape does not remove elements, attributes, or script text, and it does not reason about HTML or JavaScript context.

Do not treat html.escape as a substitute for a dedicated HTML sanitizer, a template system that auto-escapes, or a policy for untrusted markup. The strings below are printed as data; they are not executed in a browser on this page.

escape does not sanitize markup or JavaScript URLs

html.escape(s, quote=True)

Tags are character-escaped, not removed. A javascript: URL has no special characters to escape, so it is left unchanged.

ParameterDescription
sThe input string. escape does not parse it as HTML.

Returns: A str in which only &, <, >, and, by default, quotes have been replaced.

  • This is a character-level demonstration, not a vulnerability report and not a promise that escaped output is safe in every context.
python
import html

print(html.escape('<script>alert(1)</script>'))
print(html.escape('javascript:alert(1)'))

Expected output

&lt;script&gt;alert(1)&lt;/script&gt;
javascript:alert(1)

Related: HTML escape tool, html.escape

Official documentation →