WASM의 한계와 호환 안 되는 라이브러리
WASM 내보내기는 매력적입니다. 서버 없이 Python 코드가 브라우저에서 돌아갑니다. 그런데 바로 이 지점에서 현실적인 한계가 등장합니다. 모든 Python 패키지가 WASM 환경에서 동작하지는 않습니다.
이 챕터는 그 이유를 설명하고, 어떤 패키지가 문제가 되는지, 그리고 WASM 배포를 선택해야 하는 상황과 피해야 하는 상황을 정리합니다.
왜 모든 패키지가 동작하지 않는가
Pyodide는 CPython을 WebAssembly로 컴파일한 구현입니다. 브라우저 안에서 Python 인터프리터 자체가 실행됩니다. 그러나 Python 패키지를 설치할 때는 조건이 있습니다.
패키지 설치는 pip를 통해 이루어지지만, WASM 환경에서는 네이티브 C/C++ 확장을 빌드할 수 없습니다. 브라우저는 컴파일 도구가 없고, WebAssembly는 기존 플랫폼 ABI와 다릅니다. 따라서 Pyodide에서 설치 가능한 패키지는 두 종류로 제한됩니다.
첫째, 순수 Python으로만 작성된 패키지입니다. C 확장 없이 Python 코드만으로 구성된 패키지는 대부분 설치됩니다.
둘째, Pyodide 팀이 미리 WebAssembly용으로 빌드해 배포한 패키지입니다. numpy, pandas, scipy, matplotlib 등 데이터 과학에서 자주 쓰는 라이브러리 상당수가 이 목록에 포함되어 있습니다.
이 두 조건 중 하나도 해당되지 않는 패키지는 Pyodide에서 설치할 수 없습니다.
대표적인 비호환 패키지 패턴
네이티브 C 확장에만 의존하거나 OS 수준 기능이 필요한 패키지는 WASM에서 동작하지 않습니다.
대표적인 비호환 사례는 다음과 같습니다.
jax(jaxlib에 네이티브 바이너리 의존)- 일부 데이터베이스 드라이버 (네이티브 소켓/파일 I/O 의존)
- 파일시스템 직접 접근이 필요한 패키지
- 네트워크 소켓을 직접 여는 패키지
일반적으로 비호환이 의심되는 패턴은 다음과 같습니다.
- 패키지가 설치 시
gcc나g++를 요구하는 경우 ctypes나cffi로 네이티브 라이브러리를 직접 로드하는 경우- 파일 시스템 경로에 직접 접근하거나 소켓을 직접 여는 코드
Polars와 DuckDB는 동작하나요
PART 04에서 Polars와 DuckDB를 사용했습니다. 이 두 라이브러리는 WASM에서 동작할까요?
솔직하게 답하면, "환경에 따라 다릅니다"가 가장 정확한 답입니다.
Polars는 Pyodide 배포 목록에 일부 포함되어 있지만, 모든 버전·모든 기능이 완전히 지원된다고 단정할 수 없습니다. DuckDB 역시 일부 DB 드라이버나 확장 기능은 네이티브 바이너리에 의존합니다.
Pyodide의 지원 패키지 목록은 Pyodide 버전에 따라 달라집니다. 교재를 작성하는 시점과 여러분이 실제로 내보내기를 실행하는 시점 사이에 지원 범위가 변경될 수 있습니다. 교재가 "Polars가 된다"거나 "DuckDB가 안 된다"고 단정하는 것은 신뢰할 수 없는 정보를 전달하는 것입니다.
실제로 확인하는 가장 좋은 방법은 두 가지입니다.
첫째, marimo의 린트 규칙 MW003을 활용합니다. 다음 절에서 설명합니다.
둘째, marimo export html-wasm으로 내보낸 결과물을 python -m http.server로 실제로 열어보는 것입니다. 패키지 설치 오류가 있으면 브라우저 콘솔에 오류 메시지가 나타납니다.
MW003 린트 규칙으로 비호환 패키지 감지하기
marimo 에디터에는 WASM 비호환 패키지를 미리 감지하는 린트 규칙이 내장되어 있습니다. 규칙 코드는 MW003: incompatible-package입니다.
노트북 코드에서 import 문을 분석해, Pyodide와 호환되지 않는 것으로 알려진 패키지가 사용되고 있으면 경고를 표시합니다. WASM으로 내보내기 전에 린트 경고를 먼저 확인하는 습관을 들이면 예상치 못한 오류를 줄일 수 있습니다.
MW003 경고가 없다고 해서 완전히 안전한 것은 아닙니다. MW003은 알려진 비호환 패키지를 정적 분석으로 감지하는 것이며, 미처 목록에 등재되지 않은 패키지나 런타임 오류까지 잡아내지는 못합니다. 경고 확인 후 실제 내보내기와 브라우저 테스트를 병행하는 것이 좋습니다.
WASM 환경의 추가 제약
패키지 호환성 외에도 WASM 환경에는 몇 가지 구조적 제약이 있습니다.
파일 시스템 접근이 제한됩니다. 서버에서 실행할 때는 로컬 디렉토리에 파일을 읽고 쓸 수 있지만, WASM 환경에서는 브라우저의 가상 파일 시스템을 사용합니다. 노트북이 open("data.csv")처럼 로컬 파일을 읽는다면, WASM 내보내기 후에는 그 파일을 찾을 수 없습니다.
외부 네트워크 호출이 제한됩니다. 브라우저에서 실행되는 코드는 CORS(교차 출처 자원 공유) 정책의 영향을 받습니다. HTTP 요청을 보내는 코드가 있다면 CORS 제한으로 실패할 수 있습니다.
데이터를 미리 포함하거나 URL 기반 접근으로 전환해야 하는 경우가 생깁니다. 소규모 데이터셋은 노트북 코드 안에 직접 포함하거나, CORS를 허용하는 공개 URL에서 불러오는 방식으로 전환해야 합니다.
WASM이 적합한 경우와 적합하지 않은 경우
이 모든 제약을 고려해 WASM 배포를 선택해야 하는 상황과 피해야 하는 상황을 정리합니다.
| 상황 | WASM 적합 여부 | 이유 |
|---|---|---|
| numpy, pandas, matplotlib만 사용 | 적합 | 사전 빌드 패키지, 호환됨 |
| 소규모 데이터셋을 코드 안에 포함 | 적합 | 파일 접근 없음 |
| 서버 인프라 없이 공유하고 싶은 경우 | 적합 | 정적 호스팅으로 배포 가능 |
| 교육 목적으로 코드 수정을 허용하고 싶은 경우 | 적합 | --mode edit 활용 |
| jax, 네이티브 DB 드라이버 등 사용 | 부적합 | 비호환 패키지 |
| 로컬 파일을 직접 읽는 코드 포함 | 부적합 | 파일 시스템 제약 |
| 외부 API 호출, 소켓 통신 포함 | 신중히 검토 | CORS 및 네트워크 제약 |
| 대용량 데이터 처리 | 신중히 검토 | 브라우저 메모리 한계 |
| Polars, DuckDB 기반 앱 | 직접 테스트 필요 | Pyodide 버전·설정에 따라 다름 |
WASM이 맞지 않는다면
WASM의 한계에 부딪혔다면, 서버 기반 배포를 선택하는 것이 현실적입니다. Ch 04에서 Docker 컨테이너로 marimo 앱을 서버에 배포하는 방법을 다룹니다. 서버 배포는 패키지 제약이 없고 파일 시스템과 네트워크에도 자유롭게 접근할 수 있습니다.
다음 단계
WASM의 강점과 제약을 모두 살펴봤습니다. 패키지 제약이 있거나 서버 수준 기능이 필요한 앱은 Docker 기반 서버 배포가 더 안정적인 선택입니다. 다음 챕터에서 Dockerfile 작성부터 컨테이너 실행까지 다룹니다.
정리
- WASM 환경(Pyodide)은 순수 Python 패키지 또는 Pyodide 팀이 미리 WebAssembly용으로 빌드한 패키지만 설치할 수 있습니다.
jax나 네이티브 C 확장에만 의존하는 라이브러리는 동작하지 않습니다.- Polars와 DuckDB의 WASM 지원 여부는 Pyodide 버전에 따라 달라집니다. MW003 린트 경고 확인과 실제 브라우저 테스트로 직접 검증하는 것이 가장 정확합니다.
- MW003 린트 규칙은 알려진 비호환 패키지를 정적 분석으로 감지합니다. 내보내기 전에 먼저 확인하세요.
- 파일 시스템 직접 접근이나 외부 네트워크 호출이 필요한 앱은 WASM 대신 서버 배포(Ch 04)를 선택하세요.