Streamlit Favicon: Add a Custom Tab Icon Step by Step

You've built a clean Streamlit dashboard, shared the link with your team, and then someone asks: “Why does the browser tab show a generic Streamlit logo instead of our brand?” The fix is one parameter you probably skipped: page_icon. This tutorial shows you exactly how to set a Streamlit favicon using a local image, an emoji, or a URL, and how to verify it actually appears in the tab.

What page_icon actually controls

Streamlit renders your app inside a page it generates. The st.set_page_config() function accepts a page_icon argument that tells Streamlit which icon to use for the browser tab and, in some browsers, for bookmarks. It is not a full HTML favicon stack — it is Streamlit's own hook for the tab icon.

According to the HTML specification, a favicon is declared with a rel="icon" link in the document head (WHATWG HTML spec). Streamlit handles that link for you when you pass page_icon. If you want the full context on what a favicon is and where it appears, see our guide to what a favicon is.

Prerequisites

• A working Streamlit app (any version that supports st.set_page_config).
• An icon file: a square PNG, JPG, or SVG. For best results, use a square image at least 64×64 px.
• Basic familiarity with running streamlit run app.py.

Step-by-step: set your Streamlit favicon

Step 1 — Call set_page_config first

st.set_page_config() must be the first Streamlit command in your script. If you call st.title() or any other Streamlit function before it, Streamlit raises an error. Put it at the very top of your app file, right after imports.

import streamlit as st

st.set_page_config(
    page_title="My Dashboard",
    page_icon="icon.png"
)

st.title("My Dashboard")

Step 2 — Point page_icon at your image

The page_icon value can be:

• A relative path to an image file in your project, like "icon.png".
• An absolute path, like "/home/user/app/icon.png".
• A URL to an image, like "https://example.com/icon.png".
• A single emoji character, like "🚀".

For a brand icon, a local PNG or SVG is the most reliable choice. Keep the file in the same directory as your app script, or use a path relative to where you run streamlit run.

Step 3 — Use an emoji if you don't have an image yet

If you're prototyping, an emoji is the fastest option. Streamlit converts it to an icon for the tab:

st.set_page_config(page_title="Prototype", page_icon="📊")

This is handy for internal tools, but it won't match your brand. When you're ready to ship, swap it for a real image file.

Step 4 — Prepare a proper icon file

Streamlit accepts common image formats, but a square PNG with a transparent background works best across browsers. If you only have a logo, crop it to the mark and resize it to 64×64 or 128×128 px. Our guide to making a favicon from an image walks through the cropping and simplification steps.

If you need an ICO file for other surfaces, you can convert your PNG with Mzu favicondl. Streamlit itself does not require ICO, but having one helps if you also serve the app behind a custom domain that uses a traditional favicon.

Step 5 — Verify the tab icon

Run your app, open it in a browser, and look at the tab. If you still see the default Streamlit icon, do a hard refresh (Ctrl+Shift+R or Cmd+Shift+R). Browsers cache favicons aggressively, so the old icon can stick around even after your code change. For a deeper checklist, see favicon not showing.

Common pitfalls

• Calling set_page_config too late. It must be the first Streamlit call. Moving it to the top fixes the error.
• Wrong file path. A relative path is resolved from the directory where you launch Streamlit, not from the script's folder. Use an absolute path if you're unsure.
• Non-square images. A wide logo gets squashed or letterboxed. Crop to a square first.
• Browser cache. The tab may show the old icon for a while. Hard refresh or test in a private window.
• Deployment path differences. On Streamlit Community Cloud or a container, the working directory may differ from your local setup. Use a path relative to the app file or an absolute path that exists in the deployed environment.

When you need more than page_icon

page_icon covers the browser tab for the Streamlit app itself. If you embed the app in a larger site, or if you need Apple Touch icons and a web app manifest, those are separate concerns handled by the surrounding HTML. For a complete icon stack, see our favicon best practices.

Setting a Streamlit favicon is a one-line change once you know where to put it. Start with st.set_page_config(page_title=..., page_icon=...) at the top of your script, use a square PNG or SVG, and verify with a hard refresh. That's enough to replace the default Streamlit logo with your own brand in the tab.