FAQ: 설치 오류

오류: quickjs wheel 빌드 실패 - Microsoft Visual Studio 오류

일반적인 오류 메시지

PyGWalker를 설치할 때 다음과 같은 오류 메시지가 나타날 수 있습니다:

• ERROR: Failed building wheel for quickjs
• error: Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.42.34433\bin\HostX86\x64\cl.exe' failed with exit code 2
• error D8024 : incompatible-pointer-types
• [end of output] note: This error originates from a subprocess, and is likely not a problem with pip
• ERROR: Could not build wheels for quickjs, which is required to install pyproject.toml-based projects
• Building wheel for quickjs (setup.py) ... error
• error: Microsoft C++ 14.0 or greater is required

영향을 받는 환경

• 운영 체제: Windows 10/11
• Python 버전: Python 3.7, Python 3.8, Python 3.9
• 설치 방법: pip install pygwalker
• 자주 발생: 새 Python 설치, C++ 빌드 도구가 없는 가상 환경

빠른 해결 방법

해결책 1: 사전 빌드된 wheel 설치 (추천 - 컴파일 필요 없음)

pip install --only-binary :all: pygwalker

해결책 2: Python 업그레이드 (가장 효과적)

# Python 3.9 이상(3.10, 3.11, 3.12 권장)으로 업그레이드
# python.org에서 다운로드한 후 실행:
pip install --upgrade pip
pip install pygwalker

해결책 3: Microsoft C++ Build Tools 설치 (Windows 사용자용)

1. Microsoft C++ Build Tools (opens in a new tab) 다운로드
2. 설치 프로그램을 실행하고 "Desktop development with C++" 선택
3. 명령 프롬프트/터미널 재시작
4. 다시 설치 시도:

pip install pygwalker

대체 해결 방법

Anaconda/Miniconda 사용 (C 의존성 자동 처리)

conda install -c conda-forge pygwalker

WSL/Linux 사용자용

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3-dev build-essential
pip install pygwalker
 
# CentOS/RHEL/Fedora
sudo yum install python3-devel gcc gcc-c++
pip install pygwalker

특정 버전 설치 (사전 빌드된 wheel 사용 가능)

# 사전 빌드된 wheel이 있는 버전 확인
pip install pygwalker==0.3.9  # 또는 최신 안정 버전

Docker 해결책 (격리된 환경)

FROM python:3.11-slim
RUN pip install pygwalker

이러한 오류가 발생하는 이유

이 오류는 다음과 같은 이유로 발생합니다:

1. quickjs는 C/C++ 컴파일이 필요한 의존성입니다
2. Windows에는 기본적으로 C++ 컴파일러가 포함되어 있지 않습니다
3. Python 3.7은 최신 C++ 빌드 도구와 호환성 문제가 있습니다
4. 패키지가 사전 빌드된 wheel 대신 소스에서 빌드하려고 시도합니다

설치 후 확인

# pygwalker가 제대로 설치되었는지 확인
import pygwalker as pyg
print(pyg.__version__)

아직 문제가 있나요?

위의 방법으로도 해결되지 않는다면:

1. Python 버전 확인:

   python --version

   Python 3.8 이상을 사용 중인지 확인하세요

2. pip 캐시 삭제:

   pip cache purge
   pip install --no-cache-dir pygwalker

3. 새 가상 환경에서 설치 시도:

   python -m venv fresh_env
   fresh_env\Scripts\activate  # Windows
   # source fresh_env/bin/activate  # Linux/Mac
   pip install --upgrade pip setuptools wheel
   pip install pygwalker

4. 문제 보고:

   • GitHub Issues: PyGWalker Issues (opens in a new tab)
   • Python 버전, OS 버전, 전체 오류 로그 포함

검색 키워드

• pygwalker 설치 오류 windows
• failed building wheel for quickjs pygwalker
• pygwalker microsoft visual studio error
• pygwalker cl.exe failed with exit code 2
• pygwalker incompatible-pointer-types error
• pip install pygwalker error quickjs
• pygwalker setup.py error
• pygwalker C++ 14.0 required error
• cannot install pygwalker windows
• pygwalker build wheels failed