개요
이 문서는 Streamlit의 구성 파일인 config.toml에 대해 설명합니다. config.toml 파일은 작업 디렉토리 또는 전역 개발 환경에서 사용자의 구성 옵션을 정의할 수 있는 선택적 파일입니다. 이 문서에서는 파일의 위치, 구성 옵션 우선순위, 사용 가능한 환경 변수 및 명령줄 옵션에 대해 다루며, 각 섹션별 옵션과 예제도 함께 제공합니다.
[!tip] Streamlit 구성 파일에 대한 자세한 내용은 공식 Configuration options[^1] 문서를 참고하세요.
구성 파일의 위치 및 우선순위
-
로컬 설정:
작업 디렉토리(즉,streamlit run명령어를 호출하는 디렉토리)에.streamlit/config.toml파일을 추가합니다.[!info] 작업 디렉토리에
.streamlit폴더가 없으면 새로 생성해야 합니다. -
전역 설정:
전역.streamlit디렉토리는 Streamlit 설치 시 OS 사용자 프로필에 자동으로 추가됩니다.- MacOS/Linux:
~/.streamlit/config.toml - Windows:
%userprofile%/.streamlit/config.toml
- MacOS/Linux:
-
옵션 우선순위:
전역 구성과 로컬 구성이 모두 정의된 경우, 로컬 디렉토리의 구성 옵션이 우선합니다. 추가적으로 환경 변수 및 명령줄 옵션으로 구성 옵션을 재정의할 수 있습니다.
구성 파일 형식
config.toml 파일은 TOML[^2] 형식을 따릅니다.
예제
아래는 config.toml 파일의 간단한 설정 예제입니다.
[client]
showErrorDetails = "none"
[theme]
primaryColor = "#F63366"
backgroundColor = "black"구성 옵션 섹션 및 세부 항목
Global
옵션 예시는 아래와 같습니다.
[global]
# 기본 경고: 함수 내 위젯의 기본값과 st.session_state의 위젯 값이 중복될 때 경고를 표시합니다.
# Default: false
disableWidgetStateDuplicationWarning = false
# 스크립트를 "python my_script.py"로 실행할 때 경고를 표시합니다.
# Default: true
showWarningOnDirectExecution = trueLogger
내부 로그 설정에 관한 섹션입니다.
[logger]
# 로그 레벨: "error", "warning", "info", "debug"
# Default: "info"
level = "info"
# 로그 메시지의 문자열 포맷
# Default: "%(asctime)s %(message)s"
messageFormat = "%(asctime)s %(message)s"Client
클라이언트 페이지에서 오류 및 경고 표시 설정을 다룹니다.
[client]
# 앱에서 발생한 예외 및 사용 중단 경고를 브라우저에 표시하는 방식 설정.
# Allowed values: "full", "stacktrace", "type", "none", True (deprecated), False (deprecated)
# Default: "full"
showErrorDetails = "full"
# 도구 모음, 옵션 메뉴 및 설정 대화상자(앱 우측 상단)의 항목 표시 방식
# Allowed values: "auto", "developer", "viewer", "minimal"
# Default: "auto"
toolbarMode = "auto"
# 멀티 페이지 앱에서 기본 사이드바 페이지 네비게이션 표시 여부
# Default: true
showSidebarNavigation = trueRunner
Python 코드 실행과 관련된 옵션입니다.
[runner]
# 스크립트 내에서 변수 또는 문자열을 단독으로 입력 시 앱에 출력합니다.
# Default: true
magicEnabled = true
# 스크립트 재실행 요청 시 yield 포인트 전 즉시 처리합니다.
# Default: true
fastReruns = true
# st.session_state에 직렬화할 수 없는 데이터를 추가할 때 예외를 발생시킵니다.
# Default: false
enforceSerializableSessionState = false
# Enum 클래스 승인 방식 설정: "off", "nameOnly", "nameAndValue"
# Default: "nameOnly"
enumCoercion = "nameOnly"Server
서버 실행 관련 옵션을 설정합니다.
[server]
# 변경 감지를 위한 감시하지 않을 폴더 목록 (작업 디렉토리 기준 상대 경로 가능)
# Default: []
folderWatchBlacklist = []
# 파일 감시 방식: "auto", "watchdog", "poll", "none"
# Default: "auto"
fileWatcherType = "auto"
# 서명된 쿠키를 생성하기 위한 대칭 키 (여러 복제본에서 동일 값 사용 필요)
cookieSecret = "a-random-key-appears-here"
# 앱 시작 시 브라우저를 자동 실행하지 않도록 설정
# Default: false (특정 Linux 환경 또는 Atom 플러그인 사용 시 달라질 수 있음)
headless = false
# 파일 변경 시 스크립트를 자동 재실행
# Default: false
runOnSave = false
# 서버 접속을 위한 주소 및 포트 설정
address = ""
port = 8501
# URL의 base path 설정
baseUrlPath = ""
# CORS 보호 활성화
# Default: true
enableCORS = true
# XSRF 보호 활성화
# Default: true
enableXsrfProtection = true
# 파일 업로드의 최대 사이즈 (메가바이트 단위)
# Default: 200
maxUploadSize = 200
# WebSocket 메시지 최대 사이즈 (메가바이트 단위)
# Default: 200
maxMessageSize = 200
# WebSocket 압축 활성화
# Default: false
enableWebsocketCompression = false
# 앱 실행 디렉토리 내의 `static` 디렉토리 파일 제공
# Default: false
enableStaticServing = false
# 연결이 끊긴 세션의 TTL (초 단위)
# Default: 120
disconnectedSessionTTL = 120
# HTTPS 연결을 위한 서버 인증서 및 키 파일 (프로덕션 환경에서는 권장되지 않음)
sslCertFile = ""
sslKeyFile = ""Browser
사용자가 브라우저에서 앱에 접속하기 위한 설정입니다.
[browser]
# 브라우저가 접속할 인터넷 주소 (IP 또는 DNS, 경로 포함)
# Default: "localhost"
serverAddress = "localhost"
# Streamlit으로 사용 통계 데이터 전송 여부
# Default: true
gatherUsageStats = true
# 사용자가 접속할 브라우저 포트 (server.port와 동일 값 사용)
serverPort = 8501Mapbox
Map 관련 위젯 설정에 사용되는 Mapbox 토큰을 입력합니다.
[mapbox]
# Mapbox 토큰 설정 (st.pydeck_chart, st.map 등에서 사용)
# 토큰은 https://mapbox.com 에서 무료로 발급 가능
# Default: ""
token = ""Theme
Streamlit 앱의 테마를 설정하는 섹션입니다.
[theme]
# 사용자 정의 테마가 상속받을 기본 테마: "light" 또는 "dark"
base = ""
# 대화형 요소의 주요 강조 색상
primaryColor = ""
# 메인 콘텐츠 영역의 배경 색상
backgroundColor = ""
# 사이드바 및 대부분의 대화형 위젯에 사용되는 배경 색상
secondaryBackgroundColor = ""
# 대부분의 텍스트에 사용되는 색상
textColor = ""
# 앱 내 (코드 블록 제외) 텍스트에 사용하는 폰트: "sans serif", "serif", "monospace"
font = ""Secrets
앱 배포 시 비밀 값(Secretes)을 안전하게 관리하기 위한 경로 설정입니다.
[secrets]
# 비밀 값 검색 위치 리스트. 항목은 TOML 파일 경로 또는 Kubernetes 스타일 비밀 저장 디렉토리 경로.
# 나중에 나열된 파일의 값이 우선권을 가집니다.
files = [
"~/.streamlit/secrets.toml",
"~/project directory/.streamlit/secrets.toml",
]추가 정보
이 문서의 이전 항목으로는 Configuration 문서를, 다음 항목으로는 st.get_option 문서를 참고하세요.
또한, Streamlit과 관련된 다양한 질문은 공식 forums에서 확인할 수 있습니다.
참고문헌
