How to Deploy Streamlit Apps to the Cloud for Free

Introduction

A Streamlit app running on localhost is a demo; deployed, it’s a product you can put on your resume, share with clients, or submit as a portfolio piece. Streamlit Community Cloud hosts your apps free, straight from a GitHub repo, and deployment takes about five minutes once your repo is shaped correctly.

This guide covers the whole path: repo prep, deployment, secrets, and the three errors that account for most failed first deployments.

Step 1: Shape Your Repo

Your GitHub repo needs exactly three things (see the Git guide if the repo doesn’t exist yet):

Your app file — e.g. app.py.
requirements.txt — every import, with versions:

pip freeze > requirements.txt

Any data files your app reads — or code that downloads them.

The requirements file is where 90% of deploy failures originate. The cloud machine starts empty; if you import plotly and it’s not in requirements.txt, the app crashes with ModuleNotFoundError — locally it worked because you installed it months ago and forgot.

Step 2: Deploy

Go to share.streamlit.io and sign in with GitHub.
Click Create app → Paste repo URL.
Select your repo, branch, and the main file path (app.py).
Click Deploy.

The build log streams live: pip installing your requirements, then booting the app. Two minutes later your app lives at https://yourname-app-name.streamlit.app. Every git push to the linked branch redeploys automatically — the same push-to-deploy rhythm as the Cloudflare Pages workflow.

Step 3: Secrets the Right Way

Apps with API keys — the Mistral chatbot, the PDF chat — must not commit keys to GitHub. Streamlit’s answer is secrets management:

App settings → Secrets → edit.
Add TOML-formatted secrets:

MISTRAL_API_KEY = "sk-..."

Read them in code:

import streamlit as st
key = st.secrets["MISTRAL_API_KEY"]

Locally, the same code reads a .streamlit/secrets.toml file in your project — one code path, two environments, zero committed secrets.

The Three Classic Deploy Errors

ModuleNotFoundError — a missing requirements entry. Add it, push, the app redeploys. Check for indirect imports too: streamlit-audio-recorder pip-installs differently from its import name.
App builds but shows a blank/error screen — usually a file-not-found: the app opens data.csv with a relative path, but the cloud’s working directory differs. Use pathlib.Path(__file__).parent / "data.csv" to anchor paths to the script.
App sleeps or resets constantly — free-tier apps sleep after inactivity and restart on a fresh machine, wiping session state and files written at runtime. Persist to external storage (a database, S3) if data must survive.

Resource Limits to Know

The free tier gives each app ~1GB RAM and modest CPU — plenty for every tutorial on this site, tight for the image classifier’s TensorFlow models (use MobileNet, not ResNet) and the larger Whisper sizes (stick to tiny/base).

Key Concepts

Push-to-deploy — the repo is the deployment trigger.
requirements.txt is the machine — the cloud builds exactly what you list.
Secrets, never env vars in code — platform-managed key storage.
Ephemeral filesystem — runtime files vanish on restart.

What to Try Next

Deploy the expense tracker — then solve its CSV persistence problem with a cloud database.
Add multi-page apps with st.navigation for a portfolio of tools in one deploy.
Put your apps behind your own domain — pair with the Cloudflare Pages guide for a unified personal site.
Monitor app health with Streamlit’s built-in status dashboard.

FAQ

Is Streamlit Community Cloud really free?

Yes — unlimited apps with resource limits per app, supported by Streamlit (Snowflake). For higher limits and org features, paid tiers exist, but most learning projects never hit them.

Can I deploy private-repo apps?

Yes — authorize the Streamlit GitHub app for the repo during deployment; the flow is identical.

How do I update a deployed app?

Push to the linked branch — the app rebuilds automatically. No manual redeploy step exists, which is the feature.