Repomix는 설치 과정이 매우 가볍습니다. 한두 번 가볍게 써보고 싶은 분들은 npx로 바로 시작하고, 매일 작업에 활용하실 분들은 전역 설치나 프로젝트별 설정 파일을 통해 환경을 구축하시면 됩니다.

필요한 조건 두 가지

Repomix를 실행하려면 다음 두 가지 환경이 필요합니다.

조건	이유
Node.js 22.0.0 이상	Repomix 자체가 Node.js 환경에서 동작합니다. (package.json의 엔진 요구사항 >=22.0.0)
Git	원격 저장소를 처리하거나 깃 인식 기능을 사용할 때 필요합니다. 로컬 폴더만 묶을 때는 필수 사항이 아니지만, 설치해 두는 것을 권장합니다.

특히 Node.js 버전은 실행 실패의 가장 흔한 원인입니다. 사내 환경 등에서 구버전 Node를 사용 중이라면, nvm이나 fnm을 통해 최신 버전(22 이상)을 확보해 주세요.

설치 방법 다섯 갈래

사용 빈도와 선호하는 패키지 매니저에 따라 선택하세요.

방법	명령	추천 상황
npx (설치 없음)	npx repomix@latest	일회성 실행. 설치 과정 없이 프로젝트 폴더에서 즉시 실행
npm 전역 설치	npm install -g repomix	매일 사용하는 주력 개발 환경
Yarn 전역 설치	yarn global add repomix	Yarn을 주력으로 사용하는 환경
pnpm 전역 설치	pnpm add -g repomix	pnpm을 주력으로 사용하는 환경
Bun 전역 설치	bun add -g repomix	Bun을 주력으로 사용하는 환경
Homebrew	brew install repomix	macOS·Linux에서 brew 관리를 선호하는 환경

전역 설치를 마치면, 어떤 폴더에서든 repomix 명령어 한 단어로 실행할 수 있습니다.

Docker로 실행하기

호스트 환경에 Node.js를 설치하고 싶지 않거나, 독립된 환경에서 실행하고 싶다면 Docker 이미지를 사용하세요. 이미지는 ghcr.io/yamadashy/repomix입니다.

# 현재 디렉터리 내용을 묶을 때
docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix

# 특정 디렉터리 경로를 지정해 묶을 때
docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix path/to/directory

# 원격 저장소를 묶고 결과를 호스트의 ./output 폴더에 저장할 때
docker run -v ./output:/app -it --rm ghcr.io/yamadashy/repomix --remote yamadashy/repomix

핵심은 볼륨 마운트(-v)입니다. 컨테이너 내부의 /app 경로가 곧 결과물이 저장될 호스트의 폴더와 연결됩니다. 특히 원격 저장소를 처리할 때는 결과 파일이 컨테이너와 함께 사라지지 않도록 ./output:/app처럼 별도의 호스트 폴더를 연결해 주는 것이 안전합니다.

MCP 서버 역시 Docker로 간편하게 띄울 수 있습니다.

{
  "mcpServers": {
    "repomix-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/yamadashy/repomix", "--mcp"]
    }
  }
}

설치 확인

설치가 정상적으로 완료되었는지 확인하려면 다음 명령어를 입력하세요.

repomix --version
repomix --help

--help 명령어를 통해 제공되는 옵션들을 그룹별로 한 번 훑어보시는 것을 추천합니다. 모든 플래그를 외울 필요는 없으며, 필요한 기능이 있을 때 다시 찾아보는 가이드로 활용하세요.

VSCode 확장과 브라우저 확장

터미널이 낯설다면 에디터나 브라우저의 입구를 이용해 보세요.

• VSCode 확장 'Repomix Runner' (커뮤니티 유지): 클릭 몇 번으로 폴더를 묶고, 복사 방식(파일/내용) 선택 및 결과 파일 자동 정리가 가능합니다. 기존 repomix.config.json 설정도 그대로 인식합니다. VSCode Marketplace에서 설치하세요.
• 브라우저 확장: GitHub 저장소 페이지에 Repomix 버튼을 추가해 줍니다. Chrome Web Store와 Firefox Add-ons에서 설치할 수 있습니다. 공식 문서에 따르면 확장은 최소 권한만 요청하며 텔레메트리를 수집하지 않습니다.

단, 세밀한 옵션 조절과 재현성 있는 결과물을 얻으려면 결국 CLI와 설정 파일을 사용하는 것이 가장 확실한 방법입니다.

첫 실행이 만드는 것

프로젝트 폴더에서 npx repomix@latest를 실행하면 처리 결과가 콘솔에 표시되고, repomix-output.xml 파일이 생성됩니다. 기본 설정은 다음과 같습니다.

항목	기본 설정값
출력 파일명	repomix-output.xml
출력 포맷	xml
대상 파일 선택	.gitignore + 기본 무시 패턴 적용 (50MB 초과 파일은 제외)
보안 검사	활성화 (Secretlint 기반 민감 정보 탐지)
토큰 인코더	o200k_base

주목할 점은 첫 실행 단계부터 보안 검사가 기본으로 활성화되어 있다는 것입니다. "설치 직후에는 보안이 꺼져 있다"고 걱정하실 필요 없이 안전하게 시작하실 수 있습니다.

설정을 남기는 두 가지 방법

동일한 결과물을 반복해서 만들거나 팀원과 공유하려면 설정을 파일로 남겨야 합니다.

# 현재 프로젝트 루트에 설정 파일 생성 (팀 공유용)
repomix --init

# 내 컴퓨터 전체에 적용될 전역 설정 생성 (개인 기본값)
repomix --init --global

전역 설정 파일은 macOS·Linux의 경우 ~/.config/repomix/, Windows의 경우 %LOCALAPPDATA%\Repomix\에 저장됩니다. 설정의 적용 우선순위는 명령줄 옵션 > 로컬 설정 파일 > 전역 설정 파일 순입니다.

상세한 설정 항목과 활용법은 설정 파일 편에서 자세히 다룹니다.

이제 모든 준비가 끝났습니다. 다음 편에서는 자주 사용하는 명령줄 옵션들을 목적별로 정리해 보겠습니다.