Streamlit 멀티페이지 앱 개발 가이드: 단계별 튜토리얼

Streamlit은 데이터 사이언스와 머신러닝 프로젝트를 위한 강력한 파이썬 기반 웹 애플리케이션 프레임워크입니다. 특히 간결한 코드로 인터랙티브한 UI를 쉽게 구축할 수 있어 많은 개발자들에게 인기를 끌고 있습니다. Streamlit 1.10 버전에서는 멀티페이지 앱 기능이 추가되었으며, 이를 통해 기존의 단일 페이지 방식에서 벗어나 더욱 구조화된 애플리케이션을 만들 수 있습니다.

이번 가이드에서는 기존의 싱글페이지 Streamlit 앱을 멀티페이지로 변환하는 과정을 단계별로 설명하겠습니다. 코드를 직접 따라 하면서 변환 과정을 이해할 수 있도록 구성하였으니, 여러분도 직접 실습해 보시기 바랍니다.

---

1. 싱글페이지 앱의 한계

Streamlit 1.10 이전에는 streamlit hello 명령어로 실행되는 데모 앱이 하나의 큰 싱글페이지로 구성되어 있었습니다. 사용자는 st.selectbox를 활용해 여러 기능을 선택하는 방식으로 사용해야 했는데, 이러한 방식은 몇 가지 한계를 가지고 있었습니다.

단점:

• 코드 유지보수 어려움: 앱의 규모가 커질수록 단일 파일 내에서 코드 관리가 복잡해집니다.
• 제한된 UI 요소: st.selectbox를 사용한 페이지 전환은 사용자 경험(UX) 측면에서 다소 불편합니다.
• 개별 페이지 커스텀 불가: st.set_page_config를 사용해 개별 페이지별 타이틀과 설정을 적용할 수 없습니다.
• URL을 통한 이동 불가: 특정 기능으로 바로 접근하는 것이 불가능합니다.

이제 이러한 한계를 극복하고, 보다 확장성과 유지보수성이 뛰어난 멀티페이지 앱으로 변환해 보겠습니다.

---

2. 멀티페이지 앱으로 변환하기

멀티페이지 앱을 만들기 위해서는 기본적으로 다음과 같은 절차가 필요합니다.

✅ 기본 설정

1. 엔트리포인트 파일(기존 hello.py)과 동일한 경로에 pages 폴더를 생성합니다.
2. hello.py 파일명을 Hello.py로 변경해 사이드바에서 대문자로 표시되도록 합니다.
3. pages 폴더 내부에 각 데모별 개별 페이지 파일을 생성합니다.

📁 폴더 구조 예시

.
├── Hello.py  # 메인 엔트리포인트
└── pages/
    ├── 1_📈_Plotting_Demo.py
    ├── 2_🌍_Mapping_Demo.py
    ├── 3_📊_DataFrame_Demo.py

✅ Hello.py 파일 생성

import streamlit as st

st.set_page_config(
    page_title="Hello",
    page_icon="👋",
)

st.write("# Welcome to Streamlit! 👋")

st.sidebar.success("Select a demo above.")

st.markdown(
    """
    Streamlit은 머신러닝과 데이터 사이언스를 위한 강력한 오픈소스 웹앱 프레임워크입니다.
    **👈 사이드바에서 데모를 선택하세요**
    다양한 예제를 직접 실행해 볼 수 있습니다!
    """
)

✅ 페이지별 파일 생성

각 개별 페이지 파일을 생성하여 해당 기능을 분리합니다.

pages/1_📈_Plotting_Demo.py

import streamlit as st
import time
import numpy as np

st.set_page_config(page_title="Plotting Demo", page_icon="📈")

st.markdown("# Plotting Demo")
st.sidebar.header("Plotting Demo")

st.write("이 데모에서는 실시간 플롯팅을 보여줍니다.")

progress_bar = st.sidebar.progress(0)
status_text = st.sidebar.empty()
last_rows = np.random.randn(1, 1)
chart = st.line_chart(last_rows)

for i in range(1, 101):
    new_rows = last_rows[-1, :] + np.random.randn(5, 1).cumsum(axis=0)
    status_text.text(f"{i}% Complete")
    chart.add_rows(new_rows)
    progress_bar.progress(i)
    last_rows = new_rows
    time.sleep(0.05)

progress_bar.empty()
st.button("Re-run")

pages/2_🌍_Mapping_Demo.py

import streamlit as st
import pandas as pd
import pydeck as pdk

st.set_page_config(page_title="Mapping Demo", page_icon="🌍")

st.markdown("# Mapping Demo")
st.sidebar.header("Mapping Demo")

@st.cache_data
def load_data():
    URL = "https://raw.githubusercontent.com/streamlit/example-data/master/hello/v1/bike_rental_stats.json"
    return pd.read_json(URL)

data = load_data()
layer = pdk.Layer(
    "HexagonLayer",
    data,
    get_position=["lon", "lat"],
    radius=200,
    elevation_scale=4,
    elevation_range=[0, 1000],
    extruded=True,
)

st.pydeck_chart(
    pdk.Deck(
        map_style="mapbox://styles/mapbox/light-v9",
        initial_view_state={"latitude": 37.76, "longitude": -122.4, "zoom": 11, "pitch": 50},
        layers=[layer],
    )
)

---

3. 멀티페이지 앱 실행하기

모든 준비가 끝나면 다음 명령어로 앱을 실행합니다.

streamlit run Hello.py

실행 후 사이드바에 자동으로 페이지 목록이 표시되며, 원하는 페이지를 클릭하면 해당 데모 화면으로 이동할 수 있습니다.

---

4. 멀티페이지 앱의 장점

멀티페이지 앱으로 전환함으로써 얻을 수 있는 주요 장점은 다음과 같습니다.

✅ 코드 관리 용이: 페이지별로 파일이 분리되어 대규모 앱에서도 관리가 쉬워집니다.
✅ 개별 페이지 설정 가능: st.set_page_config를 활용해 페이지별 제목, 아이콘을 설정할 수 있습니다.
✅ URL 접근 가능: 각 페이지별 고유 URL을 제공하여 특정 기능으로 바로 접근할 수 있습니다.
✅ UX 향상: 사이드바에서 직관적으로 페이지를 이동할 수 있어 사용성이 개선됩니다.
✅ 확장성 강화: 기능을 추가하는 것이 용이하여 확장성이 뛰어납니다.

---

마무리

이번 가이드에서는 기존 싱글페이지 Streamlit 앱을 멀티페이지로 변환하는 방법을 살펴보았습니다. 간단한 폴더 구조 변경과 코드 분리를 통해 앱의 유지보수성과 확장성을 극대화할 수 있습니다. Streamlit을 활용해 보다 직관적이고 강력한 웹 애플리케이션을 개발해 보세요! 🚀