Python 패키지에서 CLI 명령 만들기 (빠른 가이드)

Source: Dev.to

요약: 패키지 메타데이터에 console_scripts 엔트리 포인트를 선언하고, 대상 가상 환경을 활성화한 뒤 pip install을 실행합니다 (개발 중에는 pip install -e .를 사용). 이렇게 하면 ./venv/bin(Unix/macOS) 또는 venv\Scripts(Windows)에 실행 파일 래퍼가 생성됩니다.

1) 예시 프로젝트 구조

myproject/
├─ pyproject.toml   ← (or setup.cfg / setup.py)
└─ src/
   └─ cli.py

src/cli.py (예시)

def main():
    print("Hello from mycmd!")

if __name__ == "__main__":
    main()

엔트리 포인트(예: mypackage.cli:main)에 지정된 함수가 설치된 명령이 실행될 때 호출됩니다.

2) 권장 방식: pyproject.toml + setuptools

빌드 백엔드로 setuptools를 사용할 경우, 다음과 같이 pyproject.toml을 추가합니다:

[build-system]
requires = ["setuptools>=61", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "mypackage"
version = "0.0.1"
description = "example package"

[project.scripts]
mycmd = "cli:main"

이렇게 하면 mycmd가 설치된 명령이 되어 cli:main을 호출합니다.

3) 또 다른 일반적인 방법: setup.cfg

프로젝트가 setup.cfg를 사용한다면:

[metadata]
name = mypackage
version = 0.0.1

[options]
packages = find:

[options.entry_points]
console_scripts =
    mycmd = cli:main

(구버전 프로젝트는 entry_points={...}가 포함된 setup.py를 아직 사용할 수 있습니다.)

4) 가상 환경에 설치하기 (먼저 활성화!)

Unix / macOS

python -m venv venv
source venv/bin/activate
pip install -e .

Windows (PowerShell)

python -m venv venv
venv\Scripts\Activate.ps1
pip install -e .

-e(editable)는 개발 중에 편리합니다. 코드를 수정하면 명령을 실행할 때 즉시 반영됩니다. pip install .(비editable)도 스크립트/바이너리를 만들지만 고정된 빌드를 설치합니다.

5) 설치된 명령 확인하기

Unix/macOS

which mycmd   # venv가 활성화돼 있으면 venv/bin/mycmd를 보여줍니다
mycmd         # 실행하고 출력 확인

예상 위치

• Unix/macOS: ./venv/bin/mycmd (실행 파일 래퍼)
• Windows: venv\Scripts\mycmd.exe (또는 mycmd-script.py)

mycmd를 실행하면 Hello from mycmd!(또는 main()에서 출력하는 내용)이 표시됩니다.

6) 참고 사항 및 모범 사례

• pip install 전에 반드시 가상 환경을 활성화하세요. 시스템/전역 설치를 원하지 않는 한 반드시 활성화해야 합니다.
• console_scripts(엔트리 포인트)가 권장되는 방법이며, OS에 맞는 래퍼 스크립트를 생성하고 패키지 메타데이터와 통합됩니다.
• setup.py의 레거시 scripts= 옵션은 스크립트를 직접 복사하지만, 엔트리 포인트가 의존성 해결 및 크로스 플랫폼 동작 면에서 일반적으로 더 좋습니다.
• Click이나 Typer와 같은 라이브러리를 사용하면 더 풍부한 CLI 앱을 쉽게 만들 수 있으며, 엔트리 포인트 문법은 동일하게 유지됩니다(CLI를 호출하는 함수를 가리키면 됩니다).