How to Run a Streamlit App: Commands, Ports, and Remote Options

Q: What command runs a Streamlit app?

Use streamlit run your_script.py to start a Streamlit app.

Q: Can I run Streamlit with python -m?

Yes. python -m streamlit run your_script.py is equivalent and is often useful in IDE or environment-specific setups.

Q: How do I change the port for a Streamlit app?

Use a CLI flag such as --server.port 8502, or set the port value in .streamlit/config.toml.

Q: How do I pass my own arguments to a Streamlit script?

Add them after a double dash, for example: streamlit run app.py -- --input data.csv.

Q: How do I make Streamlit listen on a remote server address?

Run Streamlit with --server.address 0.0.0.0 and make sure the relevant port is exposed through your network and hosting setup.

Name: Olaf Källström

Updated on 3/8/2026

Running a Streamlit app usually means taking a normal Python script and launching it with the Streamlit CLI.

What "running Streamlit" actually means

For a beginner, this phrase can sound more mysterious than it is.

In practice, running a Streamlit app means:

you write a Python file that imports streamlit
you start a local Streamlit server from the terminal
Streamlit opens the app in your browser

That is the key idea: a Streamlit app is still a Python script, but you do not launch it with plain python app.py. You launch it with Streamlit so the app can render as a web interface.

Why this matters

If you use the wrong command, the app may not start correctly, your arguments may be parsed in the wrong place, or the server may bind to the wrong address or port.

This guide is meant to answer the practical questions readers usually have before they go deeper:

what command should I run?
how do I pass my own script arguments?
how do I change the port?
how do I make the app reachable remotely?
what should I use for deployment after local development?

Quick Start

This is the standard way to run a Streamlit app:

streamlit run app.py

As soon as you run that command, Streamlit starts a local server and opens the app in your default web browser.

To stop the server, return to the terminal and press Ctrl+C.

The simplest working example

Before talking about ports and deployment, it helps to see the smallest possible app.

import streamlit as st
 
st.title("Hello, Streamlit")
st.write("Your app is running.")

Save that as app.py, then run:

streamlit run app.py

That is enough to understand the core loop of Streamlit development.

Use `streamlit run` for normal workflows

This is the default command you should remember:

streamlit run your_script.py

It is the cleanest choice when:

you are working from a terminal
you are testing locally
you are using the standard Streamlit developer workflow

For most readers, this is the only command they need at first.

Run Streamlit as a Python module

Some IDEs and Python environments are easier to configure with python -m.

This command is equivalent:

python -m streamlit run your_script.py

This is especially useful when:

your IDE expects a Python module entrypoint
you want to be explicit about which Python interpreter is running Streamlit
you are debugging environment issues

If streamlit run and python -m streamlit run behave differently, you usually have a virtual environment or path problem.

Pass your own script arguments the right way

This is a common source of confusion.

If your app expects custom arguments, they must come after a double dash so Streamlit does not interpret them as Streamlit CLI options.

streamlit run app.py -- --input data.csv --mode review

Without the --, the arguments are treated as Streamlit flags instead of script arguments.

Change the port from the command line

If the default port is busy or your deployment environment expects a different port, override it at launch time.

streamlit run app.py --server.port 8502

This is also helpful when:

you want to run multiple Streamlit apps on one machine
a host expects a specific port such as 80
you want to confirm a browser cache issue by testing a fresh port

Set the server address for remote access

When you want the app to listen beyond localhost, bind it to an address that remote clients can reach.

streamlit run app.py --server.address 0.0.0.0 --server.port 8501

This is the common pattern for containers, VMs, and remote Linux servers.

It does not automatically make your app public, though. You still need the network path to be open, which may include:

firewall rules
container port exposure
reverse proxy configuration
cloud security group settings

Put repeated settings in `.streamlit/config.toml`

If you keep launching the same way, configuration is usually cleaner than repeating long CLI flags.

[server]
port = 8501
address = "0.0.0.0"
 
[browser]
gatherUsageStats = false

Streamlit configuration can be set in:

a global config file
a per-project .streamlit/config.toml
environment variables such as STREAMLIT_SERVER_PORT
CLI flags such as --server.port

CLI flags take precedence over environment variables and config files.

Useful Streamlit CLI commands beyond `run`

Once you start working with Streamlit regularly, the CLI can do more than launch apps.

Useful commands include:

streamlit run to start your app
streamlit hello to launch the example app
streamlit config show to inspect available configuration options
streamlit cache clear to clear on-disk cache
streamlit version to confirm the installed version

These are especially helpful when you are debugging environment issues or checking deployment assumptions.

Run a remote script URL

Streamlit can also run a script directly from a URL.

streamlit run https://raw.githubusercontent.com/streamlit/demo-uber-nyc-pickups/master/streamlit_app.py

This is useful for quick experiments, demos, or testing a remote example without cloning a full repository first.

Common local workflow

For most projects, a good local workflow looks like this:

create or activate a virtual environment
install streamlit
save the app as app.py or another Python file
run streamlit run app.py
leave the terminal running while you iterate

Because Streamlit is designed for rapid iteration, that terminal command becomes the center of your feedback loop.

Running Streamlit from an IDE

If you are using an IDE such as PyCharm or VS Code, the two practical approaches are:

run streamlit run app.py in the IDE terminal
configure the run target as python -m streamlit run app.py

The second option is often easier when your IDE needs an explicit Python module entrypoint.

Running Streamlit in Docker

When you containerize a Streamlit app, the most important detail is usually the entry command and network binding.

The common pattern is:

ENTRYPOINT ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]

This keeps the app reachable from outside the container, assuming the container port is exposed by your runtime.

Docker is usually the right next step when:

you want a repeatable deployment artifact
you are deploying to a VM, cloud host, or Kubernetes
your team wants environment consistency

What to use after local development

Once the app runs locally, the next question is usually deployment.

The common options are:

Streamlit Community Cloud for a quick managed path from GitHub
Docker for portable self-hosting
a VM or cloud platform when you need more control

Streamlit Community Cloud is designed to create, deploy, and manage Streamlit apps with GitHub-connected workflows, while Docker is the more flexible option when you need infrastructure control.

If you do not want to manage a server yourself

For beginners, this is usually the most practical question.

If you do not want to think about Linux setup, reverse proxies, or keeping a VM alive, start with a managed platform.

1. Streamlit Community Cloud

This is the easiest recommendation for many first-time deployments because it is the official managed path for Streamlit apps and supports free app hosting for many simple use cases.

best for a first public demo
GitHub-connected workflow
lowest setup friction

See: Streamlit Community Cloud (opens in a new tab)

2. Hugging Face Spaces

Hugging Face Spaces is a good fit when your Streamlit app is connected to ML demos, model exploration, or the Hugging Face ecosystem.

One important detail: Hugging Face now recommends using Docker Spaces for Streamlit rather than relying on the old built-in Streamlit SDK path.

good for model demos and AI interfaces
useful if your project already lives in the Hugging Face ecosystem
better when Docker-based packaging is acceptable

See: Hugging Face Spaces Overview (opens in a new tab)

3. Railway

Railway is a convenient option when you want a simple hosted deployment flow without manually managing the underlying server.

good for quick app hosting with less infrastructure work
useful when you want a more general application platform than a Streamlit-specific host

See: Railway Streamlit Template (opens in a new tab)

4. Zeabur

Zeabur is another beginner-friendly hosting option that works well when you want a faster deployment experience without handling server setup yourself.

useful for lightweight app deployments
easier entry point than self-managing a VM for many small teams

See: Zeabur Docs (opens in a new tab)

Common mistakes

1. Running the file with plain Python

If you use python app.py, you are running the script, but not launching the Streamlit app server.

2. Forgetting the `--` before script arguments

This makes your custom arguments look like Streamlit CLI options.

3. Binding only to localhost on a remote machine

If the app must be reachable from outside the host, --server.address 0.0.0.0 is the usual starting point.

4. Changing the config file and expecting every setting to hot reload

Theme changes can reflect immediately, but non-theme server settings usually require a restart.

5. Assuming a running server is automatically publicly accessible

A working app process does not mean the network path is open.

Troubleshooting

Why does `python app.py` not open the app correctly?

Because Streamlit apps should be launched through Streamlit, not plain Python. Use streamlit run app.py or python -m streamlit run app.py.

How do I stop a running Streamlit server?

Press Ctrl+C in the terminal where the app is running.

How do I pass custom arguments into my script?

Put them after a double dash, such as streamlit run app.py -- --mode dev.

Why is my remote Streamlit app not reachable?

The usual causes are binding only to localhost, not exposing the port, or not opening the network path in your host or cloud firewall.

Should I configure port and address with CLI flags or a config file?

Use CLI flags for one-off runs and a project-level .streamlit/config.toml for repeated local or deployment settings.

Related Guides

Frequently Asked Questions

What command runs a Streamlit app?

Use streamlit run your_script.py.

Can I run Streamlit with `python -m`?

Yes. python -m streamlit run your_script.py is equivalent and often useful in IDE setups.

How do I change the port for a Streamlit app?

Use a CLI flag such as --server.port 8502, or set port in .streamlit/config.toml.

How do I pass my own arguments to a Streamlit script?

Add them after --, for example streamlit run app.py -- --input data.csv.

How do I make Streamlit listen on a remote server address?

Run it with --server.address 0.0.0.0 and make sure the port is exposed through your network and hosting setup.