Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 38 ยท Deployment and Customization

Deploying to Streamlit Community Cloud

Publish a Streamlit app for free: structure the repository, write requirements.txt, add secrets, deploy from GitHub, manage updates and fix common build errors.

An app that only runs on your laptop is a draft. Streamlit Community Cloud is the quickest way to give it a public (or private) URL. You push your code to a GitHub repository, tell the service which file to run, and it installs your dependencies and starts the app. Every push to the branch redeploys automatically.

This lesson covers what the repository must contain, how to write a reliable requirements.txt, how secrets work in the cloud, the deployment steps, and the errors that hit almost everyone once. Services and screens change over time, so treat the button names as approximate and the principles as stable.

Streamlit and deployment steps cannot run on this site, so commands and files are shown read-only. The TryIt checks a requirements file the way a careful reviewer would, in plain Python.

What the repository needs

Text
my-dashboard/
โ”œโ”€โ”€ app.py                  # the entry file
โ”œโ”€โ”€ requirements.txt        # Python packages
โ”œโ”€โ”€ .gitignore
โ”œโ”€โ”€ data/
โ”‚   โ””โ”€โ”€ sample.csv          # small sample data only
โ””โ”€โ”€ .streamlit/
    โ”œโ”€โ”€ config.toml         # theme, options (safe to commit)
    โ””โ”€โ”€ secrets.toml        # LOCAL ONLY, listed in .gitignore

Three rules:

  1. The entry file runs from the repository root. Relative paths such as data/sample.csv are resolved from where the app starts, which is the repository root on the cloud. Build paths with pathlib.Path(__file__).parent / "data" / "sample.csv" so they work from anywhere.
  2. Everything needed to run must be in the repository or installable from it. The cloud machine is a fresh Linux container: it has none of your local files, environment variables or installed software.
  3. Keep the repository small. Commit sample data, not gigabytes. Large datasets and model files go in object storage and are downloaded at startup (see Saving, Loading and Sharing Models).

A typical .gitignore:

Text
.venv/
__pycache__/
.streamlit/secrets.toml
*.env
.DS_Store

requirements.txt

The cloud builds a fresh environment from requirements.txt. It must list every package you import that is not part of Python's standard library, including streamlit itself if you want a particular version.

Text
streamlit==1.52.0
pandas==2.3.3
scikit-learn==1.7.2
openpyxl==3.1.5

The numbers are examples: use the versions you actually tested with (pip show streamlit).

Pin versions with ==. Unpinned packages install the latest release at build time, so an app that worked yesterday can break after a library update. Get your current versions with pip freeze, but copy only the packages you actually use, since a full freeze lists dozens of transitive dependencies and can include things that do not install on Linux (Windows-only packages, for example).

Common traps:

  • Importing sklearn but listing sklearn instead of scikit-learn (the import name and the package name differ; the same applies to cv2 and opencv-python-headless, PIL and pillow, yaml and pyyaml).
  • Forgetting openpyxl (Excel), psycopg2-binary (PostgreSQL), or pyarrow (Parquet).
  • Using opencv-python instead of opencv-python-headless, which needs system libraries the container lacks.
  • System packages: put them in a packages.txt file, one apt package name per line.

Run this checker, which reads a requirements file and flags unpinned lines and well-known name mix-ups.

Python Review a requirements.txt

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.

The script finds four kinds of trouble that would cost you a failed build.

Secrets in the cloud

Never commit secrets.toml. In the cloud, you paste its contents into the app's Settings, in a Secrets box, using the same TOML format:

TOML
LLM_API_KEY = "paste-the-real-key-here"

[connections.sales_db]
url = "postgresql://reader:password@host:5432/shop"

Your code is unchanged: st.secrets["LLM_API_KEY"] and st.connection("sales_db", type="sql") read from there. Update a secret in the settings and the app restarts with the new value. See APIs and Secrets for how to use and protect them.

Deployment steps

flowchart LR
    A["Code in a<br/>GitHub repository"] --> B["Sign in to<br/>Community Cloud"]
    B --> C["New app:<br/>repo, branch, file"]
    C --> D["Advanced settings:<br/>Python version, secrets"]
    D --> E["Deploy: build,<br/>install, run"]
    E --> F["Public URL"]
    F -->|"git push"| E

After the first deployment, every push to the chosen branch redeploys the app.

  1. Push the repository to GitHub (public repositories work on the free tier; private ones need you to grant access).
  2. Sign in to Streamlit Community Cloud with GitHub and choose Create app.
  3. Select the repository, branch and main file path (for example app.py).
  4. Open advanced settings to choose a Python version and paste your secrets.
  5. Deploy. The log shows the dependency installation, then the app starts. A first build usually takes a few minutes.
  6. You can pick a custom sub-domain, set the app to be viewable only by invited emails, or make it public.

Free-tier behavior to plan for

  • Apps go to sleep after a period of no visitors and wake on the next visit, which takes a short while. A first user may see a "wake up" button.
  • Resources are limited (memory, CPU). Loading a large model or dataset can exceed the memory limit and the app is restarted. Reduce memory use with cache_data(max_entries=...), smaller data, or downcasting data types.
  • The disk is temporary. Files you write (SQLite databases, uploads) are lost on restart or redeploy. Use an external database or storage for anything that matters.
  • No long background jobs. The app is a web process: do heavy training elsewhere and ship the result.

Reading logs and fixing build errors

The logs are in the app's "Manage app" panel. Typical problems:

Symptom Likely cause and fix
ModuleNotFoundError: No module named 'x' Missing or misnamed line in requirements.txt
Build fails installing a package Version pinned that does not exist for your Python version; adjust it
FileNotFoundError: data/file.csv Path relative to your machine, file not committed, or wrong case (Linux is case-sensitive)
KeyError from st.secrets Secret not pasted in the cloud settings
App restarts repeatedly Out of memory: shrink data or cache less
Works locally, not on the cloud Different Python or library versions; pin them and match locally

Reproduce cloud problems locally with a clean environment: create a new virtual environment, install only from requirements.txt, and run streamlit run app.py. If it fails there, it will fail in the cloud.

Updating and rolling back

Deploying is a git push. To roll back, revert the commit and push. For risky changes, push to a branch and create a second app pointed at that branch to try it out before it reaches the main URL.

Treat the live app as production: use pinned dependencies, keep a short README with run instructions, and do not commit secrets. If you do commit one by accident, rotating the key is the only real fix.

Other places to deploy

Community Cloud is convenient but not the only choice. You can run Streamlit on any server or container platform (see Running Streamlit with Docker and a Reverse Proxy). Pick Community Cloud for demos, portfolios and internal prototypes, and a server or container platform when you need custom domains, bigger machines, single sign-on or private networking.

Common mistakes

  • Unpinned or misnamed packages in requirements.txt.
  • Absolute or Windows-style paths in the code.
  • Committing secrets.toml, or forgetting to paste secrets in the cloud.
  • Writing important data to local disk, which is lost on restart.
  • Large files in the repository or heavy work at startup that exceeds memory.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why pin package versions in requirements.txt?

    Unpinned packages install the newest release, which can break a working app without any code change.
  2. 2. What goes into the Secrets box in the cloud settings?

    The same TOML you would keep in .streamlit/secrets.toml is pasted into the app settings so st.secrets works.
  3. 3. An app saves user uploads to a local folder on Community Cloud. What is the risk?

    The container filesystem is temporary. Use an external database or object storage for data that must last.
  4. 4. The log says ModuleNotFoundError: No module named 'sklearn' even though your code imports it. What is a likely fix?

    The pip package is called scikit-learn, although the import name is sklearn.

Summary

  • Put the app, a pinned requirements.txt and a .gitignore that excludes secrets.toml in a GitHub repository.
  • Use the real pip package names (scikit-learn, pillow, pyyaml, opencv-python-headless) and pin versions.
  • Secrets are pasted into the cloud settings in TOML form and read with st.secrets.
  • Each push to the chosen branch redeploys the app; apps sleep when idle and the disk is temporary.
  • Debug builds from the logs, and reproduce failures in a clean local virtual environment.

Next: Running Streamlit with Docker and a Reverse Proxy