Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 38 ยท Deployment and Customization

Configuration and Themes

Configure Streamlit with config.toml, command-line flags and environment variables. Set themes, ports, upload limits, page title, icon and layout for your app.

Streamlit apps run well with no configuration, but real apps need decisions: a brand color, a dark theme, a different port, a larger upload limit, a hidden menu. Streamlit has one system for all of this. You can set options in a file (.streamlit/config.toml), in environment variables, or on the command line, and the same option name works in all three.

This lesson shows where each setting goes, how options override each other, how to set a theme, and how to configure each page from code with st.set_page_config.

Streamlit does not run on this site, so the app code is read-only. The runnable examples parse configuration text with Python's built-in tomllib, so you can check the TOML syntax and the override rules for real.

The config file

Create a folder called .streamlit next to your app (or in your home folder for all apps) and put config.toml in it:

TOML
# .streamlit/config.toml
[server]
port = 8501
maxUploadSize = 50        # megabytes
runOnSave = true

[browser]
gatherUsageStats = false

[theme]
primaryColor = "#0b7285"
backgroundColor = "#ffffff"
secondaryBackgroundColor = "#f1f5f9"
textColor = "#1f2937"
font = "sans serif"

The file is TOML: [section] headers and key = value lines, with strings in double quotes, booleans as true/false, and numbers bare. Each option belongs to a section such as server, browser, theme, runner, client or logger. You can list every option with streamlit config show in a terminal.

Streamlit looks in two places: ~/.streamlit/config.toml (your user-level defaults) and ./.streamlit/config.toml in the folder where you start the app. The project file wins for options it sets. The server must be started from the project folder for the local file to be found, which is a frequent cause of "my theme does not apply".

Checking TOML syntax

A syntax slip in a config file gives an error at startup. Use this TryIt to parse a config the same way Streamlit does and to see the resulting nested dictionary.

Python Parse a config.toml

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Types matter: port is an integer and runOnSave a boolean. The broken file fails because strings need quotes.

Three ways to set an option, and who wins

The same option can come from several places. From strongest to weakest:

  1. Command-line flag: streamlit run app.py --server.port 9000
  2. Environment variable: STREAMLIT_SERVER_PORT=9000
  3. Project config file: ./.streamlit/config.toml
  4. User config file: ~/.streamlit/config.toml
  5. Streamlit's built-in default

The environment variable name is STREAMLIT_ plus the section and key in upper snake case: server.maxUploadSize becomes STREAMLIT_SERVER_MAX_UPLOAD_SIZE. Environment variables are the natural choice in Docker and cloud hosts, where you do not want to edit files. This stand-in builds the variable name and resolves the winner.

Python Stand-in: option names and precedence

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Environment beats the project file, and a command-line flag beats both.

Themes

The [theme] section sets colors and fonts for the whole app:

Option Meaning
base "light" or "dark" starting point
primaryColor Buttons, sliders, links, focus rings
backgroundColor Main page background
secondaryBackgroundColor Sidebar, input boxes, code blocks
textColor Default text
font "sans serif", "serif" or "monospace"

Users can also switch between light and dark (and the system setting) from the app's Settings menu, and Streamlit follows the operating-system preference by default when you define no theme. If you want your own brand look in both modes, define separate light and dark theme blocks in newer versions (see the current docs for [theme.light] and [theme.dark]), or just choose base and a couple of colors.

Pick colors with enough contrast: text on the background should meet at least a 4.5:1 ratio so people with low vision can read it. A mid-tone primary color that is readable both as a button fill and as link text on a white background is the hardest part of choosing a palette.

Charts follow the theme where they can. Streamlit's native charts (st.line_chart, st.bar_chart) pick up theme colors, while a matplotlib figure uses its own style, so set that explicitly if you need a match.

Page settings in code: st.set_page_config

Things that belong to a single page, not the whole server, are set with st.set_page_config. It must be the first Streamlit command in the script (before any other st.* call) and is called once per run:

Python
import streamlit as st

st.set_page_config(
    page_title="Sales dashboard",      # browser tab title
    page_icon="๐Ÿ“ˆ",                    # emoji or image path
    layout="wide",                     # use the full width, not a narrow column
    initial_sidebar_state="expanded",  # or "collapsed" / "auto"
    menu_items={
        "Get help": "https://example.com/help",
        "Report a bug": "https://example.com/bug",
        "About": "### Sales dashboard\nInternal tool, version 1.4",
    },
)

layout="wide" is what most dashboards want, because the default centered layout wastes space on big screens. menu_items customizes the three-dot menu; setting "Get help": None hides an entry.

In a multipage app each page file may call set_page_config, but the entry file's call usually decides the defaults.

Hiding Streamlit's own chrome

Sometimes an embedded or public app should look cleaner. A few official options exist:

TOML
[client]
toolbarMode = "minimal"       # "auto", "developer", "viewer" or "minimal"
showErrorDetails = "none"     # do not show stack traces to visitors

[ui]
hideTopBar = true

showErrorDetails = "none" is worth setting in production: stack traces can reveal file paths and code. The exact option set changes between versions, so confirm it with streamlit config show for the version you deploy.

Useful server options

Option What it does
server.port Port to listen on (default 8501)
server.address Interface to bind to (0.0.0.0 inside containers)
server.headless true = do not open a browser window (servers)
server.maxUploadSize Maximum upload in MB (default 200)
server.enableCORS, server.enableXsrfProtection Cross-site protections; keep the defaults on
server.baseUrlPath Serve under a sub-path such as /dashboard (reverse proxies)
server.runOnSave Rerun when the file changes
runner.fastReruns Rerun without waiting for the old run to stop
browser.gatherUsageStats Send anonymous usage statistics

Leave the two protection options enabled unless you have read about what they guard against. Turning them off to make an embedding error go away is a common way to open a security hole.

Where not to put configuration

Application secrets go in secrets.toml (see APIs and Secrets), not config.toml, because the config file is normally committed to git and the secrets file never is. A theme or a port is public; a database password is not.

Common mistakes

  • Starting the app from a different folder, so the project config.toml is not found.
  • Missing quotes around strings in TOML.
  • Calling st.set_page_config after another Streamlit command.
  • Putting passwords in config.toml.
  • Turning off XSRF or CORS protection to silence a warning.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which source wins if the same option is set on the command line and in config.toml?

    Command-line flags override environment variables, which override the config files, which override defaults.
  2. 2. What is the environment variable for server.maxUploadSize?

    The name is STREAMLIT_ plus the section and option in upper snake case.
  3. 3. Where must st.set_page_config be called?

    It has to be the first Streamlit call, otherwise Streamlit raises an error.
  4. 4. Which is the right place for a database password?

    Secrets are kept separate from configuration so they are never committed.

Summary

  • Options live in .streamlit/config.toml, environment variables (STREAMLIT_SECTION_OPTION) or command-line flags; flags win, then environment, then project and user files.
  • [theme] controls colors and fonts; keep contrast high.
  • st.set_page_config sets title, icon, layout and menu, and must be the first Streamlit call.
  • server.maxUploadSize, server.port and client.showErrorDetails are common production settings.
  • Keep secrets out of config.toml, and keep CORS and XSRF protections on.

Next: Deploying to Streamlit Community Cloud