Hugging Face Spaces는 Streamlit, Gradio, Static 웹 앱을 손쉽게 배포할 수 있는 매우 편리한 플랫폼입니다. 그러나 Streamlit 앱을 배포할 때 예상치 못한 실행 실패가 발생하는 경우가 종종 있습니다. 이 번에는 “Hugging Face Spaces 앱에서 Streamlit 실행 실패”라는 주제로, 그 원인과 구체적인 해결 방법을 단계별로 설명드리겠습니다.
목차
실행 실패 증상
먼저 실행이 실패하는 경우 어떤 식으로 나타나는지를 알아보겠습니다.
- 앱 로딩 화면에서 무한 로딩
- “Error occurred while running app” 메시지 출력
- Spaces 앱이 꺼지거나 로딩조차 되지 않음
- 앱 실행 후 하얀 화면만 출력됨
이러한 현상이 발생할 경우 대부분은 코드 구성 문제, 환경설정 누락, 또는 필수 파일 미포함 등이 원인입니다.
Hugging Face Spaces Streamlit 실행 실패 원인
1. requirements.txt 누락 또는 구성 오류
Spaces에서 Streamlit 앱이 실행되기 위해서는 의존성 패키지를 명시한 requirements.txt 파일이 반드시 필요합니다.
[예시]
streamlit==1.34.0
pandas
numpy
requirements.txt가 없거나 streamlit 패키지가 누락되어 있으면 앱 실행 시 오류가 발생합니다.
해결 방법:
- 루트 디렉토리에
requirements.txt파일을 반드시 포함시키고, 필요한 패키지를 정확히 명시하세요.- Streamlit 버전을 명확히 지정하는 것이 좋습니다.
2. 잘못된 디렉토리 구조 또는 파일 위치 오류
Streamlit 앱은 일반적으로 app.py, main.py 또는 streamlit_app.py 파일을 진입점으로 인식합니다. 그러나 이 파일이 루트가 아닌 하위 폴더에 있을 경우 실행되지 않습니다.
해결 방법:
streamlit_app.py또는app.py파일을 루트 경로에 위치시키세요.- GitHub에서 Push할 때 올바른 파일 위치인지 반드시 확인하세요.
3. 잘못된 Python 코드 또는 Streamlit 함수 사용 오류
Streamlit에서 지원하지 않는 함수나 외부 리소스 사용 시 앱이 강제 종료되거나 실행이 멈춥니다. 특히 input() 함수처럼 콘솔 입력을 받는 함수는 사용할 수 없습니다.
해결 방법:
- 콘솔 입력 대신
st.text_input(),st.selectbox()등의 Streamlit 컴포넌트를 사용하세요.- 코드 실행 전에 로컬에서 먼저 실행해 오류가 없는지 테스트하세요.
4. .gitattributes, .gitignore 등 설정 파일의 문제
일부 설정 파일이 필수 리소스를 Git에서 제외시켜 실행 실패로 이어질 수 있습니다.
해결 방법:
.gitignore에requirements.txt또는 주요 Python 파일이 포함되어 있지 않은지 확인하세요.- 필요시 설정 파일을 재구성해 포함 항목을 점검하세요.
5. 리소스 부족 (RAM/디스크 사용량 초과)
Spaces의 무료 플랜에서는 RAM과 저장소 제한이 존재합니다. 이미지 파일이 많거나 대용량 모델을 로드하는 경우 실행이 제한될 수 있습니다.
해결 방법:
- 가능하면 리소스를 경량화하세요.
- 필요 시 Hugging Face Pro 플랜을 고려할 수 있습니다.
단계별 문제 해결 가이드
1단계. 로컬에서 Streamlit 앱 정상 실행 확인
streamlit run app.py
먼저 로컬에서 실행되는지 확인해보세요. 실행에 문제가 없다면 다음 단계로 넘어갑니다.
2단계. GitHub 파일 업로드 구조 점검
streamlit_app.py또는app.py가 루트에 있어야 합니다.requirements.txt가 반드시 포함되어 있어야 합니다.
3단계. Hugging Face Spaces 새 앱 생성
- Spaces 페이지에서
Create New Space클릭 - Framework: Streamlit 선택
- GitHub 저장소 연결
- App 생성
4단계. 로그 확인 오류 분석
실행 실패 시 로그에서 다음 항목을 확인하세요.
ModuleNotFoundErrorFileNotFoundErrorTypeError또는ValueError
이를 통해 어떤 패키지나 파일이 문제인지 쉽게 파악할 수 있습니다.
문제 해결 후 점검 사항
- 앱이 정상 실행되는지 재확인
- 다른 사용자도 접근 가능한지 테스트
- 모델 로드, 외부 API 연결 등 기능이 모두 작동하는지 확인
마무리 요약
Hugging Face Spaces 앱에서 Streamlit 실행 실패 문제는 대부분 사소한 설정 오류나 파일 누락으로 발생합니다. 위에서 설명한 단계별 가이드를 통해 원인을 점검하고 수정하면 대부분의 문제는 빠르게 해결됩니다.
requirements.txt반드시 포함app.py또는streamlit_app.py는 루트에 위치- Streamlit 전용 함수만 사용
- 실행 로그 분석으로 문제 원인 파악
이 가이드를 참고하면, Hugging Face Spaces에서 안정적으로 Streamlit 앱을 실행할 수 있을 것입니다. 직접 작업하면서 문제를 해결하는 과정을 익히면, 향후 유사한 상황에서도 빠르게 대처할 수 있습니다.