pyRevit로 시작하는 Revit 자동화 스크립팅 입문

Revit 자동화를 배우고 싶은데 C#과 비주얼 스튜디오, 그리고 플러그인 빌드·배포까지 넘어야 한다면 진입 문턱이 꽤 높다. pyRevit은 그 문턱을 크게 낮춘다. 파이썬 스크립트를 리본 버튼으로 등록해 클릭 한 번으로 실행하는 오픈소스 확장 도구로, 컴파일도 배포용 설치 파일도 필요 없다. 스크립트 파일을 정해진 폴더 구조에 넣기만 하면 Revit 리본에 버튼이 생긴다. 이 글은 pyRevit의 설치와 확장·번들 구조, 첫 스크립트 작성, 그리고 RevitPythonShell과의 차이와 배포 방법까지 입문에 필요한 뼈대를 정리한다.

■ pyRevit이 잘하는 일

pyRevit은 “입력이 같으면 결과도 같은” 반복 업무에 특히 강하다. 실무에서 흔히 이렇게 쓴다.

뷰·시트 이름을 사무소 표준에 맞게 일괄 변경
스프레드시트의 실(室) 데이터를 모델 파라미터로 동기화
제출 전 필수 파라미터 누락 여부를 검사하는 QC 스크립트
신규 모델의 기본 뷰 속성 일괄 설정, 미태그 요소 일괄 태깅

손으로 하면 반나절 걸리고 실수가 끼는 일을 몇 초로 줄여 준다. 공식 문서와 커뮤니티 예제로 시작해 조금씩 자기 업무에 맞게 고쳐 쓰는 방식이 가장 현실적이다.

■ 설치와 확장·번들 구조

pyRevit은 설치 관리자로 설치하면 Revit에 pyRevit 탭이 자동으로 붙는다. 여기에 내 도구를 얹으려면 확장(extension)이라는 폴더를 하나 만들고 pyRevit 설정에서 그 경로를 등록하면 된다. 구조는 폴더 이름의 접미사로 역할이 정해지는 규칙이라 외우기 쉽다.

폴더 접미사	역할
`.extension`	확장의 최상위 컨테이너
`.tab`	리본의 탭
`.panel`	탭 안의 패널(버튼 묶음)
`.pushbutton`	실제 실행 버튼(스크립트 담김)
`.pulldown / .stack`	드롭다운·세로 묶음 등 배치

계층은 이렇게 중첩된다.

MyTools.extension/
└─ MyOffice.tab/
   └─ QC.panel/
      └─ RenameSheets.pushbutton/
         ├─ script.py      ← 버튼 클릭 시 실행되는 파이썬
         └─ icon.png       ← 버튼 아이콘(선택)

버튼 폴더 안에서 이름이 script.py로 끝나는 파일이 그 버튼의 실행 스크립트가 된다. 고급 설정이 필요하면 같은 폴더에 bundle.yaml로 툴팁·권한 등을 지정한다.

■ 첫 스크립트: 파이썬으로 Revit API 호출

RenameSheets.pushbutton/script.py에 아래를 넣고 Revit에서 pyRevit 탭을 다시 읽으면(Reload) 버튼이 생긴다. 프로젝트의 모든 벽 인스턴스를 세어 알림창에 띄우는 예시다. C#에서 쓰던 FilteredElementCollector·Transaction이 그대로, 문법만 파이썬으로 바뀐다.

# -*- coding: utf-8 -*-
from pyrevit import revit, DB, forms

doc = revit.doc   # 현재 열린 문서

# 배치된 벽 인스턴스만 조회 (C#과 동일한 API)
walls = (DB.FilteredElementCollector(doc)
           .OfCategory(DB.BuiltInCategory.OST_Walls)
           .WhereElementIsNotElementType()
           .ToElements())

forms.alert("벽 개수: {}".format(len(walls)), title="pyRevit")

값을 바꾸는 스크립트라면 트랜잭션으로 감싼다. pyRevit은 with revit.Transaction("이름"): 구문으로 Start·Commit을 자동 처리해 준다.

from pyrevit import revit, DB

doc = revit.doc
walls = (DB.FilteredElementCollector(doc)
           .OfCategory(DB.BuiltInCategory.OST_Walls)
           .WhereElementIsNotElementType()
           .ToElements())

with revit.Transaction("벽 주석 입력"):
    for w in walls:
        p = w.LookupParameter("Comments")
        if p and not p.IsReadOnly:
            p.Set("검토완료")

여기서 알 수 있듯 pyRevit로 배우는 것은 파이썬 문법이 아니라 Revit API 그 자체다. 컬렉터로 모으고 트랜잭션으로 고치는 흐름을 익혀 두면 나중에 C#으로 넘어가도 개념이 그대로 이어진다.

■ pyRevit vs RevitPythonShell

구분	pyRevit	RevitPythonShell(RPS)
주 용도	완성한 도구를 리본 버튼으로 배포	대화형 셸에서 즉석 실험·탐색
실행 방식	버튼 클릭 → script.py 실행	REPL에 한 줄씩 입력
배포	폴더 공유·Git으로 팀 배포 쉬움	개인 실험에 적합
버전	Revit 2026까지 대응	Revit 2025·2026 지원 재개됨

둘은 경쟁이라기보다 역할이 다르다. RPS의 대화형 셸로 API를 이것저것 눌러 보며 익힌 뒤, 쓸 만한 코드가 나오면 pyRevit 버튼으로 굳혀 팀에 배포하는 흐름이 자연스럽다. 실제로 pyRevit 번들에서 RPS 명령을 링크 버튼으로 호출할 수도 있어 둘을 섞어 쓰기도 한다.

■ 팀 배포 방법

혼자 쓸 때는 확장 폴더 경로만 등록하면 끝이지만, 팀에 나눠 줄 때는 확장 폴더를 Git 저장소로 관리하는 방식을 권한다. 각자 그 저장소를 pyRevit 확장 경로로 등록해 두면, 저장소를 pull 받는 것만으로 새 도구와 수정 사항이 모두에게 반영된다. 네트워크 공유 폴더에 확장을 두고 여러 PC가 같은 경로를 바라보게 하는 방법도 흔하다. 어느 쪽이든 스크립트를 고치면 Revit의 pyRevit 리로드 한 번으로 즉시 갱신된다는 점이 배포·유지보수를 편하게 만든다.

■ 눈여겨볼 것

pyRevit의 기본 엔진은 오랫동안 IronPython(파이썬 2 계열)이었다. 최근 버전은 CPython(파이썬 3) 엔진도 함께 지원하지만, 예전 예제 중에는 파이썬 2 문법(예: print 문)이 섞인 것이 있어 실행 엔진에 따라 오류가 날 수 있다. 스크립트 상단에서 어떤 엔진으로 도는지 확인하고, 인코딩 선언(coding: utf-8)을 붙여 한글 주석·문자열이 깨지지 않게 한다. 또 Revit API의 대량 수정 스크립트는 반드시 사본 모델에서 먼저 검증한 뒤 실제 프로젝트에 적용한다.

■ 이런 분께 도움이 됩니다

C# 없이 Revit 자동화를 시작하려는 실무자 — 파이썬만으로 리본 버튼을 만들 수 있다
반복 QC·이름 정리에 지친 BIM 코디네이터 — 몇 초짜리 스크립트로 시간을 되찾는다
Revit API를 배우려는 학생·주니어 — 컴파일 없이 API 개념을 바로 실험할 수 있다

■ 참고

pyRevit 설치 관리자와 지원 Revit 버전, 확장 폴더 등록 방법은 공식 문서(pyrevitlabs) 기준으로 확인한다. 폴더 접미사 규칙과 bundle.yaml 옵션은 버전에 따라 세부가 달라질 수 있으므로, 최신 문서의 예제로 첫 확장을 만들어 보는 것이 가장 빠른 길이다.