Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 38 ยท Getting Started

Install Streamlit and Run Your First App

Install Streamlit in a virtual environment, run the hello demo, write app.py, start it with streamlit run, change the port and stop the server on any system.

Getting a Streamlit app on screen takes four steps: create an isolated Python environment, install the package, write a script, and start the server. This lesson walks through each, shows what to expect in the browser, and explains the most common startup problems.

Everything here happens on your own computer, because Streamlit is a server you run yourself. The commands below are real; the code examples are read-only Streamlit, with runnable stand-ins at the end to practice the script structure.

Step 1: a virtual environment

A virtual environment is a private folder of Python packages for one project, so Streamlit's dependencies (pandas, NumPy, Tornado and others) never clash with other projects. Use a currently supported Python 3 version.

Terminal
mkdir my-first-app
cd my-first-app

# create and activate the environment
python -m venv .venv

# macOS / Linux
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

When the environment is active, your terminal prompt usually starts with (.venv). If python is not found on your system, try python3.

Step 2: install Streamlit

Terminal
pip install streamlit
streamlit --version

pip downloads Streamlit and its dependencies, including pandas and NumPy. To record what you installed so a teammate (or a server) can repeat it, write a requirements.txt:

Terminal
pip freeze > requirements.txt

Better still, keep a short hand-written requirements.txt that lists only the packages you really import, for example streamlit and matplotlib, and pin versions once the app is stable.

Step 3: try the built-in demo

Streamlit ships with a demo app. It is a good way to check the installation and see the library's range of widgets and charts.

Terminal
streamlit hello

The first time, Streamlit may ask for an email address for product updates; you can press Enter to skip it. Your browser opens at http://localhost:8501 showing a welcome page with a sidebar of demos (animation, plotting, mapping and a data frame explorer). Stop the server by pressing Ctrl+C in the terminal.

Step 4: write and run your own app

Create a file named app.py in your project folder. Any file name works; app.py and streamlit_app.py are the common ones. (Do not name it streamlit.py, because it would shadow the real library and Python would import your file instead.)

Python
import streamlit as st

st.title("Hello, Streamlit")
st.write("This page was built with Python only.")

name = st.text_input("What is your name?")
if name:
    st.success(f"Nice to meet you, {name}!")

Run it:

Terminal
streamlit run app.py

The terminal prints a Local URL (usually http://localhost:8501) and a Network URL that other computers on your network can use. A browser tab opens with the title, a line of text and an empty text box. Type "Ada" and press Enter: a green message box appears saying "Nice to meet you, Ada!". Clear the box and the message disappears, because the script reran with an empty string and if name: was false.

flowchart TD
    A["python -m venv .venv"] --> B["pip install streamlit"]
    B --> C["write app.py"]
    C --> D["streamlit run app.py"]
    D --> E["browser opens localhost:8501"]
    E --> F["edit app.py and save"]
    F --> E

After the first run you stay in the last two steps: edit, save, look at the browser.

Useful streamlit run options

Command Effect
streamlit run app.py Start the app on port 8501
streamlit run app.py --server.port 9000 Use another port (handy if 8501 is busy)
streamlit run app.py --server.headless true Do not open a browser (servers, containers)
python -m streamlit run app.py Same, but uses the Python of the active environment
streamlit run app.py -- --name Ada Everything after -- goes to your script's sys.argv
streamlit config show Print every configuration option and its current value

If streamlit is "not recognized" after installing, the environment is probably not active, or the scripts folder is not on PATH. python -m streamlit run app.py avoids the problem.

Common problems

  • Port already in use: another Streamlit app is running. Stop it with Ctrl+C or pass --server.port.
  • Blank page or "connection error": the server stopped or the browser points at the wrong port. Look at the terminal.
  • ModuleNotFoundError: the package is installed in a different environment from the one running the app. Activate the right .venv first.
  • Code runs but nothing shows up: you forgot to call an st. function. Plain print() writes to the terminal, not the page. (The next-but-one lesson shows a shortcut that displays bare values.)

Practice without a server: a mock st

You cannot start Streamlit in the browser here, but you can still practice reading a script and predicting the page. The block below is a stand-in written for this course. It defines a tiny FakeSt whose methods print a text description of each element instead of drawing it, then runs a script string against it. Streamlit itself is not involved.

Python Stand-in: what would this script show?

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.

Both runs execute the same script text. Only the value returned by the text box differs, and the green message appears only when it is not empty. That is exactly how a real Streamlit rerun behaves.

Practice: the data a first app might show

Real first apps usually show a table or chart. Create the data in pandas first and check it in the console; once it looks right, you would hand it to st.dataframe() or st.line_chart() (covered in Chapter 2).

Python Prepare data for a first chart (pandas)

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.

In a real app, st.line_chart(visits) would draw these seven points as a line. The index becomes the x axis because it is a date column.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command starts a Streamlit app saved in app.py?

    streamlit run starts the server and opens the page; running the file with python alone would execute the script without a server.
  2. 2. Why should you not name your script streamlit.py?

    A local file named streamlit.py shadows the installed package, so import streamlit loads your script.
  3. 3. Your app should run on port 9000. What do you add?

    The server.port option sets the port; the browser then uses http://localhost:9000.
  4. 4. You call print('hi') in app.py. Where does the text appear?

    print writes to the process's standard output. To show text on the page use st.write or another st function.

Summary

  • Create a virtual environment, pip install streamlit, and verify with streamlit hello.
  • Write a script such as app.py (never streamlit.py) and start it with streamlit run app.py.
  • The app lives at http://localhost:8501; change the port with --server.port.
  • print() goes to the terminal; use st. functions to put content on the page.
  • A mock st is a good way to practice predicting what a script shows.

Next: The Rerun Model