<h1>The Application Context<aclass="headerlink"href="#the-application-context"title="Link to this heading">¶</a></h1>
<p>The application context keeps track of the application-level data during
a request, CLI command, or other activity. Rather than passing the
application around to each function, the <aclass="reference internal"href="api.html#flask.current_app"title="flask.current_app"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">current_app</span></code></a> and
<p>This is similar to <aclass="reference internal"href="reqcontext.html"><spanclass="doc">The Request Context</span></a>, which keeps track of
request-level data during a request. A corresponding application context
is pushed when a request context is pushed.</p>
<sectionid="purpose-of-the-context">
<h2>Purpose of the Context<aclass="headerlink"href="#purpose-of-the-context"title="Link to this heading">¶</a></h2>
<p>The <aclass="reference internal"href="api.html#flask.Flask"title="flask.Flask"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Flask</span></code></a> application object has attributes, such as
<aclass="reference internal"href="api.html#flask.Flask.config"title="flask.Flask.config"><codeclass="xref py py-attr docutils literal notranslate"><spanclass="pre">config</span></code></a>, that are useful to access within views and
<aclass="reference internal"href="cli.html"><spanclass="doc">CLI commands</span></a>. However, importing the <codeclass="docutils literal notranslate"><spanclass="pre">app</span></code> instance
within the modules in your project is prone to circular import issues.
When using the <aclass="reference internal"href="patterns/appfactories.html"><spanclass="doc">app factory pattern</span></a> or
writing reusable <aclass="reference internal"href="blueprints.html"><spanclass="doc">blueprints</span></a> or
<aclass="reference internal"href="extensions.html"><spanclass="doc">extensions</span></a> there won’t be an <codeclass="docutils literal notranslate"><spanclass="pre">app</span></code> instance to
import at all.</p>
<p>Flask solves this issue with the <em>application context</em>. Rather than
referring to an <codeclass="docutils literal notranslate"><spanclass="pre">app</span></code> directly, you use the <aclass="reference internal"href="api.html#flask.current_app"title="flask.current_app"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">current_app</span></code></a>
proxy, which points to the application handling the current activity.</p>
<p>Flask automatically <em>pushes</em> an application context when handling a
request. View functions, error handlers, and other functions that run
during a request will have access to <aclass="reference internal"href="api.html#flask.current_app"title="flask.current_app"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">current_app</span></code></a>.</p>
<p>Flask will also automatically push an app context when running CLI
commands registered with <aclass="reference internal"href="api.html#flask.Flask.cli"title="flask.Flask.cli"><codeclass="xref py py-attr docutils literal notranslate"><spanclass="pre">Flask.cli</span></code></a> using <codeclass="docutils literal notranslate"><spanclass="pre">@app.cli.command()</span></code>.</p>
</section>
<sectionid="lifetime-of-the-context">
<h2>Lifetime of the Context<aclass="headerlink"href="#lifetime-of-the-context"title="Link to this heading">¶</a></h2>
<p>The application context is created and destroyed as necessary. When a
Flask application begins handling a request, it pushes an application
context and a <aclass="reference internal"href="reqcontext.html"><spanclass="doc">request context</span></a>. When the request
ends it pops the request context then the application context.
Typically, an application context will have the same lifetime as a
request.</p>
<p>See <aclass="reference internal"href="reqcontext.html"><spanclass="doc">The Request Context</span></a> for more information about how the contexts work
and the full life cycle of a request.</p>
</section>
<sectionid="manually-push-a-context">
<h2>Manually Push a Context<aclass="headerlink"href="#manually-push-a-context"title="Link to this heading">¶</a></h2>
<p>If you try to access <aclass="reference internal"href="api.html#flask.current_app"title="flask.current_app"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">current_app</span></code></a>, or anything that uses it,
outside an application context, you’ll get this error message:</p>
<divclass="highlight-pytb notranslate"><divclass="highlight"><pre><span></span><spanclass="x">RuntimeError: Working outside of application context.</span>
<spanclass="x">This typically means that you attempted to use functionality that</span>
<spanclass="x">needed to interface with the current application object in some way.</span>
<spanclass="x">To solve this, set up an application context with app.app_context().</span>
</pre></div>
</div>
<p>If you see that error while configuring your application, such as when
initializing an extension, you can push a context manually since you
have direct access to the <codeclass="docutils literal notranslate"><spanclass="pre">app</span></code>. Use <aclass="reference internal"href="api.html#flask.Flask.app_context"title="flask.Flask.app_context"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">app_context()</span></code></a> in a
<codeclass="docutils literal notranslate"><spanclass="pre">with</span></code> block, and everything that runs in the block will have access
to <aclass="reference internal"href="api.html#flask.current_app"title="flask.current_app"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">current_app</span></code></a>.</p>
<p>If you see that error somewhere else in your code not related to
configuring the application, it most likely indicates that you should
move that code into a view function or CLI command.</p>
</section>
<sectionid="storing-data">
<h2>Storing Data<aclass="headerlink"href="#storing-data"title="Link to this heading">¶</a></h2>
<p>The application context is a good place to store common data during a
request or CLI command. Flask provides the <aclass="reference internal"href="api.html#flask.g"title="flask.g"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">g</span><spanclass="pre">object</span></code></a> for this
purpose. It is a simple namespace object that has the same lifetime as
an application context.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">g</span></code> name stands for “global”, but that is referring to the
data being global <em>within a context</em>. The data on <codeclass="docutils literal notranslate"><spanclass="pre">g</span></code> is lost
after the context ends, and it is not an appropriate place to store
data between requests. Use the <aclass="reference internal"href="api.html#flask.session"title="flask.session"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">session</span></code></a> or a database to
store data across requests.</p>
</div>
<p>A common use for <aclass="reference internal"href="api.html#flask.g"title="flask.g"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">g</span></code></a> is to manage resources during a request.</p>
<olclass="arabic simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">get_X()</span></code> creates resource <codeclass="docutils literal notranslate"><spanclass="pre">X</span></code> if it does not exist, caching it
as <codeclass="docutils literal notranslate"><spanclass="pre">g.X</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">teardown_X()</span></code> closes or otherwise deallocates the resource if it
exists. It is registered as a <aclass="reference internal"href="api.html#flask.Flask.teardown_appcontext"title="flask.Flask.teardown_appcontext"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">teardown_appcontext()</span></code></a>
handler.</p></li>
</ol>
<p>For example, you can manage a database connection using this pattern:</p>
<p>During a request, every call to <codeclass="docutils literal notranslate"><spanclass="pre">get_db()</span></code> will return the same
connection, and it will be closed automatically at the end of the
request.</p>
<p>You can use <aclass="reference external"href="https://werkzeug.palletsprojects.com/en/stable/local/#werkzeug.local.LocalProxy"title="(in Werkzeug v3.1.x)"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">LocalProxy</span></code></a> to make a new context
local from <codeclass="docutils literal notranslate"><spanclass="pre">get_db()</span></code>:</p>
<p>Accessing <codeclass="docutils literal notranslate"><spanclass="pre">db</span></code> will call <codeclass="docutils literal notranslate"><spanclass="pre">get_db</span></code> internally, in the same way that
