Learn, create and have fun with Python

Dash Project Structure: Multi-Tab App with Callbacks in Different Files

Template for Dash application with multiple tabs and callback definitions in different files.

As a project grows, there is a need to organize the repository for clarity and ease of maintenance.

Here’s a strategy for breaking out a Dash app into manageable pieces. The following structure groups logical parts of the app into different directories, allowing clean, maintainable and scalable architecture for (almost) any Dash project. This layout covers a multi-tab dashboard app with callback definitions in separate files. The important thing here is to import all parts correctly to prevent circular imports and to expose callbacks to the Dash app instance.

The overall structure scales nicely: tabs can be replaced with URLs, data manipulation modules can be added, layout and callbacks can be further split, etc.

In a nutshell, the project structure looks like this.

|--- dashboard/
|        |--- assets/
|                 |--- favicon.ico
|                 |___ style.css
|        |--- layout/
|                 |--- callbacks/
|                          |--- callbacks1.py
|                          |___ callbacks2.py
|                 |--- header.py
|                 |--- tab_1.py
|                 |___ tab_2.py
|        |--- content.py
|        |___ index.py
|--- app.py
|--- Procfile

The Dash app is organized into a dir called project with a module app.py, which is the entry point to the app. The actual Dash instance (app) is found in the dashboard/index.py. This separation is required to avoid circular imports (more on that later).

The project directory contains:

  1. dashboard/ dir (with app instance, layout and assets);
  2. Procfile for running in Gunicorn;
  3. requirements.txt with all dependencies;
  4. app.py the entry point to the app that imports everything else and initiates server (for running in Gunicorn).
# app.py
from dashboard.content import app

server = app.server
if __name__ == "__main__":

Let’s have a look at the dashboard/ directory. Here we have all the files for application layout and all callbacks organized in separate directories.

  1. assets/ with custom stylesheets, favicon, logos and other static elements;
  2. layout/ with app components including header, tabs, callbacks, etc;
  3. content.py which contains callbacks imports so they can be registered with Dash app instance;
  4. index.py with Dash app definition.
# index.py
from dash import Dash
import dash_bootstrap_components as dbc

external_stylesheets = [dbc.themes.BOOTSTRAP, "./assets/style.css"]
app = Dash(
app_title = "Dash project structure template"
app.title = app_title

Though callbacks are defined separately, each of them needs to be imported in content.py to be registered with the Dash instance.

# content.py
from dashboard.index import app
from dashboard.layout.callbacks import callbacks1
from dashboard.layout.callbacks import callbacks2
from dashboard.layout.header import header
import dash_html_components as html
import dash_core_components as dcc

tabs = dcc.Tabs(
        dcc.Tab(label="Tab1", value="tab-1"),
        dcc.Tab(label="Tab2", value="tab-2"),
tabs_content = html.Div(id="tabs-example-content", className="main-panel")
app.layout = html.Div(

And finally layout/ directory with, as mentioned above, all components for the app and callbacks.

  1. callbacks/;
  2. header.py;
  3. tab_1;
  4. tab_2.

How to avoid circular imports.
We need the app instance for each callback module, and we need callbacks to be registered with the app. If we put the app and layout in one file, say content.py, this module will import each callback module. But if each callback module tried to import from the content.py, this would create a circular dependency, and the import chain would fail.
This is why we need to separate app instance (index.py) and app layout.
For each callback module, we import the Dash instance from the index.py. And the content.py module imports each callback module, thus avoiding circularity.

To put it simply: first, create app instance (index.py), secondly – create layouts and callbacks (layout/), after that assign layout to the app (content.py), and finally run the app (in app.py).

# callbacks2.py
from dashboard.index import app
from dashboard.layout.tab_1 import tab_1
from dashboard.layout.tab_2 import tab_2
from dash.dependencies import Input, Output

@app.callback(Output("tabs-example-content", "children"), Input("app-tabs", "value"))
def callback2(tab):
    if tab == "tab-1":
        return tab_1
    elif tab == "tab-2":
        return tab_2
Dash app template with multi-tabs and callbacks in different files
Dash app template with multiple tabs and callbacks in different files


  1. Dash tabs
  2. Dash Multi-Page Apps and URL Support
  3. Callbacks and circular imports
  4. Structuring a multi-tab app
  5. Dash clean architecture
  6. Plotly Dash boilerplate for multi page App

Have another approach? Let me know in the comments!

One thought on “Dash Project Structure: Multi-Tab App with Callbacks in Different Files

  1. Hi!

    Good setup! Do you have a Git repo with the callbacks1.py and callbacks2.py implemented? Looking for example of factoring out the majority of my primary callbacks effecting the data structures into separate files.

    Thank you!

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top