Streamlit 1.66.0: on_change="ignore"와 st.form 선택 기준

여러 입력을 제출할 때 함께 전달하려면 st.form을 먼저 검토하세요. 다른 필드의 선택지는 즉시 바꾸면서 일부 입력의 재실행만 미루려면 on_change="ignore"를 선택적으로 쓰면 됩니다. 다만 ignore로 미룬 값은 원하는 ‘적용’ 버튼을 누르기 전에도, 다른 위젯이 일으킨 재실행을 통해 서버에 도착할 수 있습니다. 조회와 저장의 실행 조건은 별도로 정해야 합니다.

Streamlit 1.66.0은 2026년 10월 14일 16:08 UTC에 공개됐습니다. Python 3.11 이상이 필요하며 라이선스는 Apache-2.0입니다. 이번 버전에서는 Python 3.10 지원이 빠졌으므로, 해당 환경을 쓰고 있다면 UI 변경보다 실행 환경 검토가 먼저입니다. 공식 릴리스와 버전 고정 패키지 설정에서 확인할 수 있습니다.

이 글은 공식 문서와 1.66.0 태그의 자료를 검토한 설계 가이드입니다. 예제 앱을 실행하거나 처리 시간을 측정하지 않았으며, 아래 검증 목록은 적용 전에 수행할 항목입니다.

1. 이번에 달라진 범위

on_change="ignore" 자체는 1.63.0에서 st.slider와 st.text_input에 도입됐습니다. 이후 지원 범위가 넓어졌고, 1.66.0에는 st.pills, st.segmented_control, st.feedback, st.color_picker, st.datetime_input, st.camera_input, st.audio_input, st.data_editor, st.pagination 지원이 추가됐습니다. 2026년 공식 릴리스 노트

따라서 검토 대상은 ‘앱의 모든 위젯에 같은 옵션을 붙이기’보다, on_change를 지원하는 입력 중 즉시 반응할 필요가 없는 항목을 고르는 일입니다. on_click을 쓰는 버튼까지 이 설정으로 통일할 수 있다고 해석하면 안 됩니다.

2. 입력부터 저장까지 네 단계를 구분하기

혼자 만들거나 작은 팀이 운영하는 관리 화면에서는 입력값 하나를 곧바로 현재 조회 조건으로 쓰기 쉽습니다. ‘적용’ 버튼을 추가할 때는 다음 네 단계가 언제 이어지는지 먼저 적어 두는 편이 안전합니다.

1. 브라우저에서 편집한 값: 사용자가 화면에서 보고 있는 내용입니다.
2. 서버가 받은 값: Python 코드가 이번 실행에서 사용할 수 있는 내용입니다.
3. 적용하기로 확정한 조건: 앱이 사용자의 적용 동작을 받아 별도로 채택한 내용입니다.
4. 실제 업무 처리: 확정한 조건으로 조회하거나 파일을 처리하거나 데이터베이스에 저장하는 단계입니다.

ignore를 지정한 입력은 화면에서 바뀌어도 그 변경만으로 앱을 다시 실행하지 않습니다. 이후 브라우저에서 다른 위젯을 조작해 재실행이 발생하면, 대기 중이던 값도 Python에 전달됩니다. 그 위젯이 적용 버튼일 필요는 없습니다. 반면 브라우저의 새 요청 없이 서버에서 st.rerun()만 호출하는 것으로는 대기 중인 값을 새로 가져오지 않습니다. 1.66.0 공식 성능 가이드와 관련 문서 변경의 구분입니다.

이 동작에 맞춰 설계하려면 서버에 값이 도착했다는 사실과 사용자가 조회·저장을 승인했다는 사실을 분리해야 합니다. 단순히 버튼을 화면에 두는 것만으로는 부족합니다. 실제 조회나 저장 코드가 적용 동작을 조건으로 실행되도록 구성해야 합니다. 폼의 제출 역시 데이터베이스의 트랜잭션이나 저장 성공까지 보장하지는 않습니다.

3. 화면의 요구사항으로 선택하기

• 입력을 한 묶음으로 제출해야 한다: st.form이 먼저입니다. 폼 안에서 편집한 일반 입력값은 그 폼의 제출 동작으로 전달됩니다. 폼 바깥의 무관한 위젯 때문에 앱이 재실행돼도, 아직 제출하지 않은 폼 편집값이 함께 제출되지는 않습니다.
• 한 입력이 다른 입력의 선택지를 바꾼다: 선택지를 결정하는 입력은 반응형으로 유지하세요. 즉시 다른 UI를 바꾸지 않는 입력에만 ignore를 검토합니다. 모든 입력을 폼에 넣으면 제출 전에는 의존 필드의 선택지를 갱신하기 어렵습니다.
• 독립적인 화면 한 부분만 자주 갱신한다: st.fragment로 재실행 범위를 나눌 수 있는지 먼저 살펴보세요. fragment는 독립된 영역의 실행 범위를 다루며, 그 자체로 제출 시점을 정하는 장치는 아닙니다.
• 같은 데이터나 계산을 반복해서 사용한다: 캐싱 적용 가능성을 먼저 검토하세요. 입력 시점 제어와 중복 계산 문제를 따로 다룰 수 있습니다.

폼과 fragment의 기본 동작은 폼 문서와 fragment 문서를 참고하세요. 어느 방식을 선택해도 실제 응답 시간과 외부 호출량은 앱 구조에 따라 달라집니다. 이번 옵션만으로 특정 성능 향상을 약속할 근거는 없습니다.

4. 상품 조회 화면에 적용해 보기

다음은 실행 결과가 아닌 설계 예시입니다. ‘상품군 → 세부 품목’으로 선택지가 연결되고, 검색어와 가격 상한을 입력한 뒤 ‘조회 적용’을 누르는 내부 도구를 생각해 보겠습니다.

• 상품군: 바뀌면 세부 품목 목록도 바뀌어야 하므로 기본 재실행 동작을 유지합니다.
• 세부 품목·검색어·가격 상한: 다른 필드의 구성을 바꾸지 않는다는 전제에서만 ignore 후보로 둡니다. 가격 상한이 미리보기 차트까지 바꿔야 한다면 그 필드는 제외합니다.
• 조회 적용: 현재 입력 조합이 유효한지 확인하고, 그 조합을 ‘적용된 조건’으로 채택한 다음 조회합니다.
• 기존 결과: 화면에 표시 중인 결과가 어느 조건으로 생성됐는지 함께 보여 줍니다. 새 입력을 서버가 받았더라도 적용 전까지는 기존 결과와 그 조건을 유지하도록 설계할 수 있습니다.

여기서 검색어를 편집한 다음 상품군을 바꾸면, 상품군이 일으킨 재실행으로 검색어도 서버에 도착할 수 있습니다. 따라서 결과 영역이 매번 최신 위젯 값으로 곧바로 조회하는 구조라면 ‘조회 적용’의 의미가 흐려집니다. 적용된 조건과 편집 중인 조건을 구분하고, 상품군 변경 뒤에는 세부 품목이 새 목록에 속하는지도 확인해야 합니다.

반대로 모든 필드가 서로 독립적이고 제출 전까지 서버에 일반 입력값을 보내지 않아야 한다면, 이 정도 상태 구분을 추가하기보다 폼으로 묶는 쪽이 단순합니다. 팀에서 유지할 수 있는 상태 관리 수준까지 선택 기준에 넣으세요.

5. 놓치기 쉬운 경계 세 가지

• 새로고침: 아직 전달하지 않은 편집값은 페이지 새로고침으로 사라질 수 있습니다. 해당 위젯이 URL 바인딩을 지원하고 key와 bind="query-params"를 설정한 경우에는 URL을 통한 복원이 가능합니다. 이것은 임시 저장 기능과 다릅니다. URL에 노출해도 되는 필터에만 사용하고, 모든 입력 위젯이 지원한다고 가정하지 마세요.
• 업로드: 파일·카메라·오디오 입력은 ignore를 설정해도 업로드 자체는 즉시 이뤄집니다. 미뤄지는 것은 재실행입니다. 적용 버튼 전에는 파일 전송도 없어야 하는 요구사항을 이 옵션으로 충족할 수는 없습니다.
• 폼 내부: 폼 안의 ignore 설정은 효과가 없습니다. 폼의 제출 동작을 기준으로 설계하고, 두 기능을 겹쳐 추가적인 제어가 생긴다고 기대하지 마세요.

이 제한은 버전 고정 성능 가이드에 정리돼 있습니다. URL 바인딩의 지원 범위와 동작은 위젯 동작 문서도 함께 확인하세요.

6. 배포 전에 수행할 검증 목록

아래 항목은 이 글에서 실행하지 않았습니다. 적용할 앱의 별도 검증 환경에서 확인하세요. 재실행 횟수, 서버에서 읽은 입력값, 적용된 조건, 실제 조회·저장 호출 횟수를 따로 관찰하면 문제의 위치를 구분하기 쉽습니다. 기록에는 테스트용 값을 사용하세요.

1. 미룬 입력만 편집: ignore 필드의 값을 바꿉니다. 화면에는 새 값이 보이되 그 변경만으로 재실행이나 업무 처리가 일어나지 않는지 확인합니다.
2. 무관한 입력으로 재실행: 미룬 값을 편집한 뒤 별도의 반응형 위젯을 조작합니다. 값이 서버에 도착하더라도 조회·저장이 적용 동작 없이 실행되지 않는지 확인합니다. 폼 방식도 비교한다면, 폼 바깥 위젯을 조작했을 때 미제출 편집값이 전달되지 않는지 따로 봅니다.
3. 서버 재실행과 적용을 구분: 브라우저 이벤트 없이 서버 측 st.rerun()만 발생하는 경로에서는 대기 값이 새로 수집되지 않는지 확인합니다. 이어서 실제 적용 버튼 또는 폼 제출을 사용해 기대한 최신 값과 적용 조건이 일치하는지 확인합니다.
4. 적용 전 새로고침: 미전달 값을 편집하고 페이지를 새로고침합니다. 값 유실이 사용자가 예상할 수 있는 동작인지, URL 바인딩을 선택했다면 지원되는 필터가 URL에서 복원되는지 확인합니다.
5. 의존 필드 변경: 세부 품목을 고른 뒤 상품군을 바꿉니다. 선택지가 갱신되고, 더 이상 유효하지 않은 품목 조합으로 조회·저장되지 않는지 확인합니다.

업로드가 있는 화면은 한 항목을 더 추가하세요. ‘파일이 서버에 도착한 시점’과 ‘파싱·외부 전송·저장이 실행된 시점’을 따로 확인해야 합니다. 재실행을 미루는 옵션만으로 이 작업들이 모두 뒤로 밀렸다고 판단해서는 안 됩니다.

7. 작은 변경으로 도입하고 되돌리기

처음에는 한 화면의 독립 입력 한두 개에만 적용하는 편이 검토하기 쉽습니다. 기존 콜백이 검증이나 상태 갱신을 맡고 있었다면, on_change를 "ignore"로 바꾸면서 그 역할이 빠지지 않는지 먼저 살펴보세요. 적용 시점에 필요한 검증과 실행 조건을 마련한 뒤 위 목록을 확인합니다.

배포 전에는 사용 중인 Python 버전과 의존성 잠금 파일을 함께 기록하세요. 롤백은 추가한 ignore 설정을 제거하고 기존 콜백과 재실행 동작을 복원하는 변경으로 준비할 수 있습니다. 패키지까지 이전 버전으로 되돌려야 한다면, 이전에 검증했던 Python·Streamlit·의존성 조합을 함께 복원하는 절차를 준비하세요. 새로 만든 조회·저장 실행 조건은 옵션을 되돌린 뒤에도 의도대로 유지되는지 확인해야 합니다.

선택 기준은 간단합니다. 제출 전까지 일반 입력값을 묶어 두어야 하면 폼을, 의존 필드는 즉시 반응시키고 일부 입력만 조용히 편집해야 하면 선택적 ignore를 검토하세요. 두 경우 모두 ‘어느 값으로, 언제 실제 작업을 실행할지’를 앱이 명시적으로 정해야 사용자가 누르는 적용 버튼에 일관된 의미가 생깁니다.