Deploy a Streamlit Dashboard from GitHub: Step-by-Step

Updated 14 November 2026 · Standard formula, shown below

This guide walks you through deploying a Streamlit dashboard directly from a GitHub repository to Streamlit Community Cloud. You’ll connect your GitHub account, select the repo and branch, set the main file path, and have a live public URL in minutes—no server setup or Docker required.

What You’ll Need

A GitHub account with a repository containing your Streamlit app code (at minimum a Python file, e.g., app.py, and a requirements.txt).
The repository must be public, or you’ll need a paid Streamlit plan for private repos.
A Streamlit Community Cloud account (free, sign in with GitHub).
Your app should run locally first—test with streamlit run app.py before deploying.

Step-by-Step

Prepare your repository – Ensure your main app file (e.g., app.py) is at the repo root or note its exact path. Create a requirements.txt listing all Python packages your app imports, with version pins if needed. If you use secrets (API keys), do not commit them; Streamlit provides a secrets management feature.
Push your code to GitHub – Commit and push your changes to the branch you want to deploy (usually main or master).
Sign in to Streamlit Community Cloud – Go to share.streamlit.io and click “Sign in with GitHub”. Authorize Streamlit to access your GitHub account.
Click “New app” – On the top right, you’ll see a “New app” button. Click it.
Choose your repository – In the deployment form, select the repository from the dropdown. If you don’t see it, click “Edit” next to the GitHub account to refresh the list or adjust permissions.
Select the branch – Choose the branch that contains your app code, typically main.
Set the main file path – Enter the path to your Streamlit Python file, e.g., app.py. If it’s in a subfolder, use folder/app.py.
Click “Deploy” – Streamlit will build your app. The first build can take a few minutes. Once done, you’ll get a URL like https://yourapp.streamlit.app.
Update your app – Any push to the selected branch triggers an automatic redeploy. You can also manually redeploy from the Streamlit dashboard.

Common Mistakes

Missing requirements.txt – If you don’t list dependencies, the build fails. Include every import, even ones that seem standard (e.g., pandas, numpy).
Using a private repo without a paid plan – Streamlit Community Cloud only supports public repos on the free tier. Double-check your repo visibility.
Hardcoding secrets in the code – This is a security risk and may cause the app to fail if the secret is not present. Use st.secrets and add them in the Streamlit dashboard under “Settings” → “Secrets”.
Wrong main file path – If you enter app.py but the file is in a subfolder, the deploy fails. Verify the path relative to the repo root.
Using a Python version not supported – Streamlit Cloud supports 3.9 to 3.12. If your app needs a specific version, specify it in runtime.txt (e.g., python-3.11).
Ignoring build errors – If the build fails, click “View logs” to see the error. Often it’s a missing package or a syntax error.

Tips

Keep your requirements.txt minimal but complete. Pinning versions avoids surprises when a package updates.
Use a .streamlit/config.toml file to set theme, server settings, or other options. For example, you can set headless = true.
Test your app locally with the same Python version as the cloud (check the Python version in the build logs).
Use st.cache_data or st.cache_resource to speed up your app, but remember that the cloud environment restarts after inactivity—caches are not persistent.
If your app uses large files or models, consider storing them in a cloud bucket (like S3) and loading them at runtime, as the cloud has limited storage.
Streamlit provides a “Manage app” dashboard where you can view logs, restart the app, and manage secrets.

Troubleshooting

Build fails with “ModuleNotFoundError” – Add the missing module to requirements.txt. Also check for typos in the import statement.
App deploys but shows an error – Check the logs in the Streamlit dashboard. Common issues: file not found, data file missing, or a runtime error. Fix and push to redeploy.
App is slow to load – This often happens if you load large data at startup. Use caching or lazy loading. Also, the free tier sleeps after 72 hours of inactivity; the first visit after sleep takes longer.
Changes not appearing after push – Ensure you pushed to the correct branch that you selected during deployment. Also, check the “Deploy” status in the dashboard—if it failed, the old version remains.
Can’t find the repository in the dropdown – Click “Edit” next to the GitHub account and re-authorize. Make sure the repo exists and you have access.
App works locally but not on the cloud – Differences in file paths (use relative paths), environment variables, and package versions are common. Use the logs to identify the exact error.

Frequently Asked Questions

Do I need to pay to deploy a Streamlit app?

No, Streamlit Community Cloud is free for public repositories. You only need a GitHub account. Private repos require a paid plan.

Can I deploy from a GitLab or Bitbucket repository?

Streamlit Community Cloud currently supports only GitHub. For other Git hosts, you can use alternative platforms like Heroku, Railway, or Hugging Face Spaces.

How do I add environment variables or API keys?

In the Streamlit dashboard, go to your app → “Settings” → “Secrets”. Add them in TOML format, e.g., api_key = "your-key". Then access them in code with st.secrets["api_key"].

Will my app update automatically when I push to GitHub?

Yes, by default, every push to the selected branch triggers a redeploy. You can also manually redeploy from the dashboard.

Can I use a custom domain for my Streamlit app?

Yes, you can set up a custom domain in the Streamlit dashboard under “Settings” → “Custom domain”. You’ll need to configure a CNAME record with your DNS provider.

What Python versions are supported?

Streamlit Community Cloud supports Python 3.9 to 3.12. You can specify a version by adding a runtime.txt file with content like python-3.11.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.