File: //usr/share/doc/python3.10-doc/html/library/cgitb.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>cgitb — Traceback manager for CGI scripts — Python 3.10.12 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?2022.1" />
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.10.12 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="chunk — Read IFF chunked data" href="chunk.html" />
<link rel="prev" title="cgi — Common Gateway Interface support" href="cgi.html" />
<link rel="canonical" href="file:///usr/share/doc/python3.10/html/library/cgitb.html" />
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<nav class="nav-content" role="navigation">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Logo"/>
</a>
<div class="version_switcher_placeholder"></div>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero"
d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z" fill="#444"></path>
</svg>
<input type="text" name="q" aria-label="Quick search"/>
<input type="submit" value="Go"/>
</form>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<h4>Previous topic</h4>
<p class="topless"><a href="cgi.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">cgi</span></code> — Common Gateway Interface support</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="chunk.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">chunk</span></code> — Read IFF chunked data</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.10/Doc/library/cgitb.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="chunk.html" title="chunk — Read IFF chunked data"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="cgi.html" title="cgi — Common Gateway Interface support"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.10.12 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
<li class="nav-item nav-item-2"><a href="superseded.html" accesskey="U">Superseded Modules</a> »</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">cgitb</span></code> — Traceback manager for CGI scripts</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-cgitb">
<span id="cgitb-traceback-manager-for-cgi-scripts"></span><h1><a class="reference internal" href="#module-cgitb" title="cgitb: Configurable traceback handler for CGI scripts. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">cgitb</span></code></a> — Traceback manager for CGI scripts<a class="headerlink" href="#module-cgitb" title="Permalink to this headline">¶</a></h1>
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.10/Lib/cgitb.py">Lib/cgitb.py</a></p>
<div class="deprecated" id="index-0">
<p><span class="versionmodified deprecated">Deprecated since version 3.11: </span>The <a class="reference internal" href="#module-cgitb" title="cgitb: Configurable traceback handler for CGI scripts. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">cgitb</span></code></a> module is deprecated
(see <span class="target" id="index-1"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0594#cgitb"><strong>PEP 594</strong></a> for details).</p>
</div>
<hr class="docutils" />
<p>The <a class="reference internal" href="#module-cgitb" title="cgitb: Configurable traceback handler for CGI scripts. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">cgitb</span></code></a> module provides a special exception handler for Python scripts.
(Its name is a bit misleading. It was originally designed to display extensive
traceback information in HTML for CGI scripts. It was later generalized to also
display this information in plain text.) After this module is activated, if an
uncaught exception occurs, a detailed, formatted report will be displayed. The
report includes a traceback showing excerpts of the source code for each level,
as well as the values of the arguments and local variables to currently running
functions, to help you debug the problem. Optionally, you can save this
information to a file instead of sending it to the browser.</p>
<p>To enable this feature, simply add this to the top of your CGI script:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">cgitb</span>
<span class="n">cgitb</span><span class="o">.</span><span class="n">enable</span><span class="p">()</span>
</pre></div>
</div>
<p>The options to the <a class="reference internal" href="#cgitb.enable" title="cgitb.enable"><code class="xref py py-func docutils literal notranslate"><span class="pre">enable()</span></code></a> function control whether the report is
displayed in the browser and whether the report is logged to a file for later
analysis.</p>
<dl class="py function">
<dt class="sig sig-object py" id="cgitb.enable">
<span class="sig-prename descclassname"><span class="pre">cgitb.</span></span><span class="sig-name descname"><span class="pre">enable</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">display</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">logdir</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">5</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">format</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'html'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#cgitb.enable" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-2">This function causes the <a class="reference internal" href="#module-cgitb" title="cgitb: Configurable traceback handler for CGI scripts. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">cgitb</span></code></a> module to take over the interpreter’s
default handling for exceptions by setting the value of <a class="reference internal" href="sys.html#sys.excepthook" title="sys.excepthook"><code class="xref py py-attr docutils literal notranslate"><span class="pre">sys.excepthook</span></code></a>.</p>
<p>The optional argument <em>display</em> defaults to <code class="docutils literal notranslate"><span class="pre">1</span></code> and can be set to <code class="docutils literal notranslate"><span class="pre">0</span></code> to
suppress sending the traceback to the browser. If the argument <em>logdir</em> is
present, the traceback reports are written to files. The value of <em>logdir</em>
should be a directory where these files will be placed. The optional argument
<em>context</em> is the number of lines of context to display around the current line
of source code in the traceback; this defaults to <code class="docutils literal notranslate"><span class="pre">5</span></code>. If the optional
argument <em>format</em> is <code class="docutils literal notranslate"><span class="pre">"html"</span></code>, the output is formatted as HTML. Any other
value forces plain text output. The default value is <code class="docutils literal notranslate"><span class="pre">"html"</span></code>.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="cgitb.text">
<span class="sig-prename descclassname"><span class="pre">cgitb.</span></span><span class="sig-name descname"><span class="pre">text</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">info</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">5</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#cgitb.text" title="Permalink to this definition">¶</a></dt>
<dd><p>This function handles the exception described by <em>info</em> (a 3-tuple containing
the result of <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a>), formatting its traceback as text and
returning the result as a string. The optional argument <em>context</em> is the
number of lines of context to display around the current line of source code
in the traceback; this defaults to <code class="docutils literal notranslate"><span class="pre">5</span></code>.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="cgitb.html">
<span class="sig-prename descclassname"><span class="pre">cgitb.</span></span><span class="sig-name descname"><span class="pre">html</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">info</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">5</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#cgitb.html" title="Permalink to this definition">¶</a></dt>
<dd><p>This function handles the exception described by <em>info</em> (a 3-tuple containing
the result of <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a>), formatting its traceback as HTML and
returning the result as a string. The optional argument <em>context</em> is the
number of lines of context to display around the current line of source code
in the traceback; this defaults to <code class="docutils literal notranslate"><span class="pre">5</span></code>.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="cgitb.handler">
<span class="sig-prename descclassname"><span class="pre">cgitb.</span></span><span class="sig-name descname"><span class="pre">handler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">info</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#cgitb.handler" title="Permalink to this definition">¶</a></dt>
<dd><p>This function handles an exception using the default settings (that is, show a
report in the browser, but don’t log to a file). This can be used when you’ve
caught an exception and want to report it using <a class="reference internal" href="#module-cgitb" title="cgitb: Configurable traceback handler for CGI scripts. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">cgitb</span></code></a>. The optional
<em>info</em> argument should be a 3-tuple containing an exception type, exception
value, and traceback object, exactly like the tuple returned by
<a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a>. If the <em>info</em> argument is not supplied, the current
exception is obtained from <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a>.</p>
</dd></dl>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="cgi.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">cgi</span></code> — Common Gateway Interface support</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="chunk.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">chunk</span></code> — Read IFF chunked data</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.10/Doc/library/cgitb.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="chunk.html" title="chunk — Read IFF chunked data"
>next</a> |</li>
<li class="right" >
<a href="cgi.html" title="cgi — Common Gateway Interface support"
>previous</a> |</li>
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.10.12 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
<li class="nav-item nav-item-2"><a href="superseded.html" >Superseded Modules</a> »</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">cgitb</span></code> — Traceback manager for CGI scripts</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2001-2025, Python Software Foundation.
<br />
This page is licensed under the Python Software Foundation License Version 2.
<br />
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br />
See <a href="/license.html">History and License</a> for more information.<br />
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
<br />
Last updated on August 15, 2025.
<a href="/bugs.html">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.3.2.
</div>
</body>
</html>