Scrapling 설치 방법: macOS·Windows·Linux에서 CLI로 웹페이지 저장하기

Scrapling은 웹사이트의 HTML 구조가 바뀌어도 이전에 찾은 요소 위치를 학습해 다시 찾아내는 적응형(adaptive) 웹 스크래핑 라이브러리다. Cloudflare Turnstile 같은 안티봇 시스템을 우회하는 브라우저 페처, 동시 크롤링을 지원하는 Spider 프레임워크, 명령줄에서 코드 없이 페이지를 긁어오는 CLI, AI 에이전트가 바로 쓸 수 있는 MCP 서버까지 한 저장소에 들어 있다. 2026년 8월 11일 기준 GitHub 스타 74,865개, BSD-3-Clause 라이선스, PyPI로 배포된다.

이 글은 Python이 설치된 macOS·Windows·Linux 각각에서 Scrapling을 설치하고, 코드 없이 페이지를 저장하는 CLI 명령까지 실행하는 순서를 다룬다. Python 자체를 설치하는 방법이나 가상환경(venv) 개념은 다루지 않으므로, 터미널에서 python3 또는 python이 이미 실행되는 상태를 전제로 한다.

사전 조건: Python 버전과 패키지 구조를 먼저 확인한다

Scrapling은 Python 3.10 이상을 요구한다. 설치 전에 버전을 확인한다.

# macOS·Linux
python3 --version
# Windows(PowerShell)
python --version

공식 PyPI 패키지는 하나지만 안에 세 개의 선택적 의존성 그룹(extras)이 나뉘어 있다는 점이 이 도구의 설치에서 가장 먼저 이해해야 할 부분이다.

설치 명령	포함 내용	바로 쓸 수 있는 것
`pip install scrapling`	파서 엔진만	`Selector`로 이미 가진 HTML 문자열 파싱
`pip install "scrapling[fetchers]"`	+ `Fetcher`·`StealthyFetcher`·`DynamicFetcher`·Spider	웹사이트를 직접 요청·크롤링
`pip install "scrapling[shell]"`	+ 인터랙티브 셸, `scrapling extract` CLI	코드 없이 터미널에서 페이지 저장
`pip install "scrapling[ai]"`	+ MCP 서버	Claude 같은 AI 에이전트에 스크래핑 도구 연결
`pip install "scrapling[all]"`	위 전부	-

기본 설치(pip install scrapling) 상태에서 from scrapling.fetchers import Fetcher를 실행하면 ModuleNotFoundError가 난다. 공식 GitHub 이슈 #343은 이 문제를 정확히 지적한다: README의 첫 예제 코드가 scrapling.fetchers를 임포트하는데, 바로 위 설치 명령은 [fetchers] 없이 적혀 있어서 따라 하다가 바로 에러를 만난다는 것이다. 처음 설치할 때는 목적에 맞는 extras를 함께 쓰는 편이 안전하다. 이 글의 CLI 실습에는 shell 그룹(자동으로 fetchers도 포함)을 쓴다.

실행 명령: macOS·Windows·Linux에서 Scrapling 설치하기

세 OS 모두 명령 형태는 거의 같다. 터미널 프로그램과 줄바꿈 문자만 다르다.

macOS: Terminal에서 설치한다

pip install "scrapling[shell]"
scrapling install

scrapling install은 Playwright 기반 브라우저(Chromium 계열)와 지문(fingerprint) 위장에 쓰는 데이터 파일을 내려받는 별도 단계다. pip install만으로는 이 단계가 실행되지 않으므로 반드시 따로 실행한다.

macOS Terminal에서 Scrapling shell 설치와 scrapling install, extract get 명령을 차례로 입력하는 화면 — 공식 설치 문서의 명령을 macOS Terminal 화면으로 정리했습니다.

Windows: PowerShell에서 설치한다

pip install "scrapling[shell]"
scrapling install

Windows PowerShell에서는 명령을 여러 줄로 이어 쓸 때 백틱(`)을 줄 끝에 붙인다. macOS·Linux의 백슬래시(\)와 다른 부분이다.

Windows PowerShell에서 Scrapling shell 설치, scrapling install, 줄바꿈 백틱을 쓴 extract get 명령을 보여주는 화면 — 공식 설치 문서의 명령을 Windows PowerShell 화면으로 정리했습니다.

Linux: Bash에서 설치하고 확인한다

pip install "scrapling[shell]"
scrapling install

Ubuntu 26.04 LTS(2026-08-18)에서 위 두 명령으로 Scrapling 0.4.14와 Chromium 계열 브라우저 설치를 마쳤다. scrapling install이 배포판의 시스템 라이브러리를 apt로 설치하려 하므로, sudo 권한 프롬프트가 뜨는 경우 터미널에서 직접 승인한다.

실행 결과: 코드 없이 `scrapling extract`로 페이지 저장하기

설치가 끝나면 파이썬 코드를 한 줄도 쓰지 않고 scrapling extract 명령으로 웹페이지를 파일로 저장할 수 있다. 출력 파일의 확장자가 결과 형식을 정한다: .md는 마크다운, .txt는 텍스트, .html은 원본 HTML이다.

scrapling extract get 'https://example.com' content.md

Ubuntu 26.04 LTS(2026-08-18)에서 -s(--css-selector) 옵션으로 CSS 선택자를 지정해 특정 요소만 저장하는 명령도 실행했다.

scrapling extract get 'https://quotes.toscrape.com/' quotes.md -s '.text'

실제 출력은 다음과 같았다.

Ubuntu 26.04 LTS 터미널에서 scrapling extract get 명령이 성공한 로그와, scrapling만 설치한 상태에서 Fetcher를 임포트할 때 나는 ModuleNotFoundError를 보여주는 화면 — Ubuntu 26.04 LTS(2026-08-18)에서 실행한 scrapling extract get 결과와 curl_cffi ModuleNotFoundError 재현 결과입니다.

같은 환경에서 pip install scrapling만 실행한 별도 가상환경을 만들어 from scrapling.fetchers import Fetcher를 실행하면 위 이미지의 ModuleNotFoundError: No module named 'curl_cffi'가 그대로 재현됐다. 이슈 #343이 지적한 문제가 2026-08-18 시점에도 남아 있다는 뜻이다.

CLI 외에도 인터랙티브 셸을 열어 바로 요청을 보내볼 수 있다.

scrapling shell

셸을 열면 get, fetch, stealthy_fetch 같은 단축 명령과 마지막으로 가져온 페이지를 담은 page 변수를 바로 쓸 수 있다는 안내가 출력된다.

MCP 서버: AI 에이전트에 Scrapling 연결하기

Scrapling은 Claude Desktop, Claude Code 같은 MCP 클라이언트에 붙일 수 있는 MCP 서버도 공식 제공한다. 설치는 ai extras를 추가하는 것만 다르고 나머지는 같다.

pip install "scrapling[ai]"
scrapling install

Claude Code에는 실행 파일 경로를 알아낸 뒤 한 줄로 등록한다. 실행 파일 경로는 OS마다 확인 명령이 다르다.

# macOS·Linux
which scrapling-mcp
# Windows
where scrapling-mcp

claude mcp add ScraplingServer "<위에서 확인한 경로>"

Claude Desktop에는 설정 파일에 서버 항목을 추가한다. 설정 파일 위치는 macOS가 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows가 %APPDATA%\Claude\claude_desktop_config.json이다.

{
  "mcpServers": {
    "ScraplingServer": {
      "command": "scrapling-mcp"
    }
  }
}

공식 문서는 scrapling-mcp만 명령 이름으로 두면 PATH를 못 찾는 클라이언트가 있을 수 있으니, 실행 파일의 전체 경로를 넣는 편이 더 안정적이라고 안내한다. MCP 서버는 get·fetch·stealthy_fetch와 각각의 비동기·배치 버전, 스크린샷, 세션 열기/닫기까지 총 10개 도구를 제공하며, CSS 선택자로 필요한 부분만 골라 AI에 넘겨 토큰 사용량을 줄이는 것이 다른 스크래핑 MCP 서버와의 핵심 차이라고 설명한다.

자주 막히는 지점과 해결법

기본 설치 뒤 `ModuleNotFoundError`가 난다

GitHub 이슈 #343에 기록된 그대로, pip install scrapling만 실행한 상태에서 scrapling.fetchers나 scrapling.spiders를 임포트하면 curl_cffi, playwright, browserforge 순서로 누락 모듈 오류가 이어진다. 하나씩 개별 설치하지 말고 pip install "scrapling[fetchers]"로 다시 설치한다.

`scrapling install`이 연결 오류로 반복해서 실패한다

GitHub 이슈 #116에는 Windows 환경에서 브라우저 지문 데이터 파일을 내려받는 중 연결이 끊기며 Error downloading input-network.zip류의 오류가 반복된 사례가 있다. 저장소 관리자는 이 오류를 GitHub 연결 문제로 지목하며 오류가 사라질 때까지 scrapling install --force를 다시 실행하라고 안내한다. 사내망·VPN 등으로 GitHub 접속이 자주 끊기는 환경에서는 네트워크를 바꿔 재시도하는 편이 빠르다.

`pip install scrapling`이 예상보다 낮은 버전을 설치한다

GitHub 이슈 #257은 Python 3.9 환경에서 pip install scrapling을 실행하면 0.3 이상이 아니라 Python 3.9와 호환되는 마지막 버전(0.2.99)이 조용히 설치된 사례를 보여준다. Scrapling 0.3부터 Python 3.10 이상을 요구하기 때문이다. 설치된 버전이 예상과 다르면 먼저 python3 --version으로 실제 실행 중인 Python 버전을 확인한다.

검증 방법: 버전 확인 후 실제 페이지 하나를 저장해 본다

scrapling --version으로 설치가 인식되는지 확인한다.
scrapling --help로 extract·install·shell·mcp 네 개의 하위 명령이 보이는지 확인한다.
실제 URL로 scrapling extract get을 실행해 결과 파일이 생성되는지, 터미널 로그에 Fetched (200)이 찍히는지 확인한다.
Fetcher·StealthyFetcher 같은 클래스를 코드에서 쓸 계획이라면 python3 -c "from scrapling.fetchers import Fetcher"가 오류 없이 끝나는지 먼저 확인한다.

scrapling --version
scrapling extract get 'https://example.com' content.md
python3 -c "from scrapling.fetchers import Fetcher"

마지막 명령에서 ModuleNotFoundError가 나면 설치 자체가 잘못된 것이 아니라 [fetchers] extras를 빼고 설치했다는 뜻이므로, 재설치가 아니라 pip install "scrapling[fetchers]" 한 줄만 추가하면 된다.

출처: Scrapling 공식 README, 공식 CLI 문서, 공식 MCP 서버 문서, GitHub 이슈 #343, GitHub 이슈 #116, GitHub 이슈 #257 (2026-08-18 확인)