대상 사용자: 프로그래머. 소스 파일 저장 때 단위 테스트나 정적 검사 명령을 다시 실행하고 싶은 Windows x64 개발자를 위한 도구입니다. 자동으로 변경을 감지하지만 실행할 검사 명령과 성공 기준은 사용자가 정합니다.
첨부 구성과 공식 원본
watchexec-2.8.0-x86_64-pc-windows-msvc.zip: 프로젝트 공식 릴리스 ZIP 원본. 실행 파일, LICENSE, README, 매뉴얼, 셸 완성 파일을 변경하지 않고 제공합니다.watchexec-2.8.0-korean-guide.zip: 이 한국어 안내, 간단한 Python 실습 코드와 검사 파일, 원본 출처·SHA-256, 공식 LICENSE 사본을 담은 별도 자료입니다. 이 설명서 ZIP에는 실행 파일이 없습니다. 실행 파일은 첫 번째 공식 원본 ZIP에 들어 있습니다.
공식 릴리스: https://github.com/watchexec/watchexec/releases/tag/v2.8.0 공식 원본: https://github.com/watchexec/watchexec/releases/download/v2.8.0/watchexec-2.8.0-x86_64-pc-windows-msvc.zip 공식 사용법: https://github.com/watchexec/watchexec/tree/v2.8.0/crates/cli 공식 소스·라이선스: https://github.com/watchexec/watchexec/tree/v2.8.0
원본 SHA-256:
0c872fc18c8e801f21614c6daf2504a5826d5c705bb67f7a583d879f5410d9ea
배포 ZIP의 Apache-2.0 LICENSE와 기존 고지·매뉴얼을 원형대로 보존했습니다. 프로그램은 upstream 프로젝트의 저작물입니다. 한국어 안내와 demo는 주식회사 제이가 작성했으며 공식 배포물과 별개입니다. demo는 자유롭게 수정·실행할 수 있습니다.
설치와 버전 확인
공식 ZIP을 내려받고 PowerShell에서 아래 명령으로 해시를 확인합니다. 경로는 실제 다운로드 위치로 바꾸세요.
Get-FileHash -Algorithm SHA256 .\watchexec-2.8.0-x86_64-pc-windows-msvc.zip
ZIP을 C:\Tools\watchexec 등 자신이 쓰는 도구 폴더에 풉니다. 압축 내부의 watchexec-2.8.0-x86_64-pc-windows-msvc 하위 폴더에 watchexec.exe가 있습니다. 탐색기에서 실행 파일 위치를 확인한 뒤 그 실제 경로로 실행하세요. 설치 마법사나 관리자 권한이 필요하지 않은 포터블 방식입니다.
$watchExe = 'C:\Tools\watchexec\watchexec-2.8.0-x86_64-pc-windows-msvc\watchexec.exe'
& $watchExe --version
& $watchExe -h
버전 문자열 첫 부분이 watchexec 2.8.0인지 확인합니다. Windows ARM64에서는 이 x64 ZIP 대신 공식 릴리스의 aarch64-pc-windows-msvc.zip을 선택하세요. Python은 watchexec 자체 실행에 필요하지 않지만 아래 실습에는 Python 3가 필요합니다. python --version으로 확인합니다.
저장할 때 단위 테스트 다시 실행
설명서 ZIP을 새 폴더에 풀고, demo가 보이는 설명서 폴더에서 PowerShell을 엽니다. 환경변수는 이 터미널 세션에만 적용됩니다.
$env:PYTHONDONTWRITEBYTECODE = '1'
python -B -m unittest discover -s demo -v
& $watchExe -w demo -e py --debounce 300ms --on-busy-update queue --shell=none -- python -B -m unittest discover -s demo -v
첫 실행에서 테스트 4개와 OK가 보입니다. watchexec는 시작하자마자 명령을 한 번 실행하고, 이후 demo 안의 .py 변경을 모아 다시 실행합니다. demo\main.py의 마지막에 주석 한 줄을 추가해 저장하세요. 테스트 출력이 다시 나타납니다. Ctrl+C로 감시를 끝냅니다.
실패도 확인하려면 demo\test_main.py에서 clamp(5, 0, 10)의 기대값 5만 6으로 바꾸어 저장하세요. 테스트가 실패해야 정상입니다. 기대값을 5로 되돌리면 다시 성공합니다. watcher가 실행 중이라는 사실과 검사 성공 여부를 구별하세요.
| 옵션 | 의미 |
|---|---|
-w demo |
demo 폴더를 재귀 감시 |
-e py |
Python 확장자 이벤트만 사용 |
--debounce 300ms |
가까운 저장 이벤트를 모아 처리 |
--on-busy-update queue |
검사 중 변경은 다음 실행으로 대기 |
--shell=none |
지정한 실행 파일과 인수를 직접 실행 |
--postpone |
필요하면 추가: 시작 시 실행 생략 |
이 예제는 서버 프로세스를 강제로 재시작하지 않습니다. 특히 Windows에서 restart 모드는 실행 중 명령을 강제 종료할 수 있습니다. DB 마이그레이션·배포·펌웨어 쓰기 명령을 감시 대상으로 지정하기 전에 반복 실행과 중단 가능성을 검토하세요. 짧은 검사 명령부터 적용하는 것이 좋습니다.
문제 해결
| 증상 | 확인·해결 |
|---|---|
| watchexec 명령을 찾지 못함 | $watchExe를 실제 exe 전체 경로로 지정하고 & $watchExe 사용 |
| python 명령이 없음 | Python 3 설치 상태 확인. PC에서 py -3만 동작하면 위 명령의 python을 py -3으로 바꾸고 --shell=none 뒤 인수로 지정 |
| 저장해도 재실행 안 됨 | -w 경로, -e 확장자와 .gitignore·.ignore를 확인. --print-events로 통과 이벤트 점검 |
| 네트워크/가상 폴더에서 변경 누락 | 필요하면 --poll 2s를 추가. 폴링은 부하와 지연이 늘 수 있음 |
| 검사 출력 파일 때문에 반복 실행 | 감시 폴더 밖으로 출력하거나 -i 'build/**' 등 제외. 이 실습은 -B로 pyc 생성을 막음 |
| 파일 하나 감시가 저장 후 끊김 | 편집기가 파일을 교체할 수 있으므로 상위 폴더를 감시하고 확장자로 좁힘 |
| 테스트가 FAIL | watcher는 검사기를 대신하지 않음. 실패한 assertion과 코드 변경을 확인 |
실행 확인 범위
2026-10-21 Windows x64 환경에서 공식 원본 ZIP의 SHA-256, ZIP 무결성, LICENSE 포함, 버전과 실습 명령을 확인했습니다. 첫 실행·Python 파일 저장 후 재실행·실패 전환과 복구·확장자 필터 동작을 확인했습니다. 네트워크 공유 폴더와 Windows ARM64, 모든 편집기 저장 방식은 실측 대상이 아닙니다.