Poetry git dependency — URL, 위치, PEP 508, 실무 패턴

Git URL 의존성, PEP 508 표준, SSH/HTTPS 인증, Poetry 2.x 위치 문제

Poetry에서 외부 Git 저장소 패키지를 의존성으로 추가할 때의 URL 형식, pyproject.toml 위치, PEP 508 표준, SSH/HTTPS 인증, 패키지 이름/임포트 이름 분리, 실무 전환 전략 등 일반 원칙을 먼저 정리하고, data_standardization 패키지 연동 사례를 다룬다.

Engineering
DevOps
Python
Poetry
Security
SSH
저자

Kwangmin Kim

공개

2025년 03월 08일

1 의존성 관리의 일반 원칙

1.1 패키지 레지스트리와 직접 URL 의존성

소프트웨어 의존성 관리에서 패키지 출처는 크게 세 가지로 나뉜다.

출처 예시 특징
공개 레지스트리 PyPI, npm, Maven Central 버전 인덱싱, 빠른 설치, 공개 패키지만 가능
사설 레지스트리 Nexus, Artifactory, GitHub Packages 조직 내 패키지 관리, 접근 제어 필요
직접 URL (Git) GitHub/GitLab repo URL 레지스트리 불필요, SSH/HTTPS 인증 필요

Python 생태계에서 직접 URL 의존성은 PEP 508 표준으로 정의된다. pip, Poetry 등 현대 패키지 관리 도구는 모두 이 표준을 지원한다.

1.2 PEP 508 — 의존성 URL 명세 표준

PEP 508은 Python 의존성을 URL로 직접 지정하는 표준 문법을 정의한다.

패키지명 @ URL

구체적으로:

requests @ https://files.pythonhosted.org/packages/.../requests-2.28.0.tar.gz
my-pkg  @ git+ssh://git@github.com/org/repo.git@main
  • @ 기호 왼쪽: 로컬에서 사용할 패키지 이름
  • @ 기호 오른쪽: 패키지를 가져올 URL
  • git+ssh://, git+https:// 등 프로토콜로 Git 저장소 직접 지정 가능

1.3 Git 의존성의 장단점

항목 장점 단점
배포 편의성 레지스트리 불필요, 즉시 연동 가능 저장소 이동 시 URL 변경 필요
버전 관리 브랜치/태그/커밋 해시로 정확한 버전 지정 레지스트리 기반보다 번거롭다
보안 SSH 키 기반으로 강력한 접근 제어 SSH 설정 오류 시 설치 실패
재현성 commit hash로 완벽한 재현 공개 패키지와 달리 미러 불가
이 글이 다루는 상황

Poetry 2.x로 관리되는 agent 프로젝트에 사내 private repo data_standardization 패키지를 Git URL 의존성으로 추가하는 과정에서, URL 형식·pyproject.toml 위치·인증 방식 등에서 여러 함정이 발생했다. 아래부터는 이 실전 사례와 함께 일반 원칙을 설명한다.

2 개요

Poetry를 포함한 현대 Python 패키지 관리 도구는 외부 Git 저장소의 패키지를 직접 의존성으로 추가할 수 있다. 이때 URL 형식, 인증 방식, pyproject.toml 내 위치, 패키지 이름/임포트 이름 분리 등 실무에서 반드시 알아야 할 일반 원칙이 있다.

  • 외부 private GitHub repository를 Poetry 프로젝트에 의존성으로 추가하려면 poetry add git+... 명령을 사용한다.
    • ex) poetry add git+ssh://git@github.com/org/repo.git@main
  • PEP 508 URL 형식은 패키지명 @ git+ssh://git@github.com/org/repo.git@브랜치 형태로 작성한다.
  • 그런데 실제로 해보면 여러 함정이 있다.
    • HTTPS vs SSH 중 어떤 URL을 써야 하는가?
      • Git URL은 HTTPS 또는 SSH 형식이 가능하지만, private repo의 경우 SSH 방식이 권장된다.
    • pyproject.toml의 어느 섹션에 추가해야 하는가?
      • Poetry 2.x에서는 git dependency를 [project.dependencies] 섹션에 PEP 508 URL 형식으로 추가해야 lock 파일에 반영된다.
      • 주의) [tool.poetry.dependencies]에 추가하면 lock 파일에 반영되지 않는다.
    • Poetry 2.x에서 달라진 것은 무엇인가?
      • Poetry 2.x부터는 Python 표준인 [project] (PEP 621)를 우선으로 사용하고, Poetry 전용 기능만 [tool.poetry]에 남겨둔다.
      • 이 혼용 방식은 git dependency를 추가할 때 위치 선택에서 혼란을 일으킨다.
    • 패키지 이름과 import 이름이 다를 때는 어떻게 관리하는가?
      • Python 패키지는 배포용 이름(설치 시 사용)과 import용 이름(코드에서 import할 때 사용)이 다를 수 있다. 보통 배포 이름에는 조직 prefix를 붙여 충돌을 방지하고, import 이름은 간결하게 유지한다. 이는 [tool.setuptools.package-dir] 등으로 매핑할 수 있다.

3 git dependency URL 형식 두 가지

Git 저장소에서 Python 패키지를 직접 설치할 때는 HTTPS와 SSH 두 가지 방식이 있다. public repo는 HTTPS로도 충분하지만, private repo는 SSH 방식이 더 안전하고 관리가 편하다. 두 방식 모두 Poetry, pip 등에서 지원한다.

3.1 HTTPS 방식

poetry add git+https://github.com/org/repo.git@main
  • public repo에서는 바로 동작
  • private repo에서는 GitHub Personal Access Token(PAT) 필요
# PAT 포함 URL (보안 주의: .env나 환경변수로 관리 필수)
poetry add git+https://<TOKEN>@github.com/org/repo.git@main

3.2 SSH 방식

poetry add git+ssh://git@github.com/org/repo.git@main
  • SSH 키 기반 인증
  • CI/CD 환경에서 deploy key 활용 가능
  • private repo 접근에 더 안전한 방식
힌트
  • 팀 단위 개발 환경이라면 SSH 방식을 추천
  • PAT는 개인 토큰이라 관리 부담이 있고 만료될 수 있다.

4 pyproject.toml에서의 위치 문제 (Poetry 2.x)

Poetry 2.x부터는 Python 표준([project], PEP 621)과 Poetry 전용([tool.poetry]) 설정이 혼용된다. git dependency는 반드시 [project.dependencies]에 PEP 508 URL 형식으로 추가해야 lock 파일에 반영된다. 위치를 잘못 지정하면 의존성 관리가 꼬일 수 있다.

  • Poetry 2.x는 [project] (PEP 621)와 [tool.poetry] 혼용 형식을 사용
  • git dependency를 어느 섹션에 넣어야 할지 헷갈리기 쉽다.

4.1 잘못된 방법 — [tool.poetry.dependencies]에 추가

# ❌ Poetry 2.x + PEP 621 혼용 시 lock 파일에 반영되지 않음
[tool.poetry.dependencies]
sg-data-standardization = {git = "git@github.com:org/repo.git", branch = "main"}
  • poetry lock을 실행해도 해당 패키지가 lock 파일에 나타나지 않는다.
  • Poetry 2.x에서 [project]를 사용하는 경우, 의존성의 source of truth는 [project.dependencies]이기 때문이다/

4.2 올바른 방법 — [project] 섹션에 PEP 508 URL로 추가

# ✅ [project.dependencies]에 PEP 508 URL 형식으로 추가
[project]
dependencies = [
    "requests (>=2.32.5,<3.0.0)",
    # ...
    "sg-data-standardization @ git+ssh://git@company_org/org/repo.git@main"
]

또는 poetry add 명령으로 자동 추가:

poetry add "git+ssh://git@company_org/org/repo.git@main"

5 PEP 508 URL 형식 분해

PEP 508은 Python 패키지 의존성을 URL로 직접 지정하는 표준 문법을 제공한다. 이 문법을 활용하면 git 저장소의 특정 브랜치, 태그, 커밋을 명확하게 지정해 설치할 수 있다. 실무에서는 SSH alias, 조직 prefix 등도 자주 활용된다.

sg-data-standardization @ git+ssh://git@company_org/department/data_standardization.git@main
│                          │   │       │              │                                   │
패키지 이름                 │   프로토콜 SSH alias      GitHub 조직/repo                     브랜치
                           URL 스킴
  • sg-data-standardization : 패키지 이름 (설치 시 사용할 이름)
  • @ : PEP 508에서 직접 URL을 지정할 때 사용하는 구분자
  • git+ssh:// : 프로토콜 (git을 SSH로 전송)
  • git@company_org : SSH 사용자 및 alias (보통 ~/.ssh/config에 정의)
  • /department/data_standardization.git : GitHub 조직/저장소 경로
  • @main : 브랜치명 (또는 태그, 커밋 해시도 가능)
구성 요소 설명
패키지명 @ PEP 508 직접 URL 지정 문법
git+ssh:// git 프로토콜 + SSH 전송
git@company_org ~/.ssh/config에 정의된 SSH alias
/department/data_standardization.git GitHub 경로
@main 브랜치, 태그, 또는 commit hash 지정 가능

5.1 브랜치/태그/커밋 지정

# 브랜치
"pkg @ git+ssh://git@github.com/org/repo.git@main"

# 태그 (버전 고정)
"pkg @ git+ssh://git@github.com/org/repo.git@v1.0.0"

# 특정 커밋 (완전한 재현성)
"pkg @ git+ssh://git@github.com/org/repo.git@f3354b9"

6 poetry add vs pyproject.toml 직접 편집

Poetry는 명령어로 의존성을 추가하는 방법과 pyproject.toml을 직접 편집하는 방법을 모두 지원한다. 명령어 사용이 안전하고 lock 파일 관리가 자동화되지만, 직접 편집은 세밀한 제어가 가능하다. 실무에서는 두 방식을 상황에 따라 병행한다.

6.1 poetry add 사용 (권장)

poetry add "git+ssh://git@company_org/department/data_standardization.git@main"
  • pyproject.toml 자동 수정
  • poetry.lock 자동 갱신
  • 의존성 해결 자동 처리

6.2 직접 편집 후 poetry lock

# 1. pyproject.toml 수정
# 2. lock 파일 갱신
poetry lock

# 3. 설치
poetry install
  • 세밀한 형식 제어 가능
  • poetry lock 실행을 잊으면 실제 설치에 반영 안 됨

7 lock 파일에서 설치 확인

Poetry는 의존성 설치 시 lock 파일에 commit hash 등 정확한 버전을 기록해, 팀원 간 환경 재현성을 보장한다. 설치 로그와 lock 파일을 통해 실제로 어떤 버전이 설치됐는지 항상 확인할 수 있다.

poetry install 성공 시 출력:

Package operations: 0 installs, 1 update, 0 removals

  - Updating sg-data-standardization
    (1.0.0 /home/.../data_standardization -> 1.0.0 f3354b9)
  • f3354b9 — remote의 최신 commit hash로 고정된 것을 확인
  • poetry.lock에는 이 commit hash가 기록되어 팀원 모두 동일한 버전 설치 보장

8 local path → git URL 전환 전략

개발 초기에는 local path로 빠르게 개발하고, 패키지가 안정되면 git URL로 전환하는 것이 실무에서 매우 효율적이다. Poetry는 두 방식을 모두 지원하며, 전환 시 lock 파일만 갱신하면 된다.

  • 만약 외부 패키지가 개발중이라면 개발 초기에는 local path로 빠르게 시작하고, 패키지가 안정되면 git URL로 전환하는 방법도 있다.
# 개발 단계 — local path (빠른 반영)
"sg-data-standardization @ file:///home/azureuser/projects/data_standardization"

# 배포/공유 단계 — git URL (재현 가능)
"sg-data-standardization @ git+ssh://git@company_org/department/data_standardization.git@main"
  • 전환 후 poetry lock && poetry install만 실행하면 된다.

9 정리

Poetry의 git dependency는 pyproject.toml 위치, URL 형식, 인증 방식, 패키지 이름/임포트 이름 분리 등 다양한 실무 패턴을 이해해야 안전하게 쓸 수 있다. PEP 508 표준과 lock 파일 관리 원칙을 숙지하면 협업과 배포가 훨씬 수월해진다.

항목 내용
HTTPS vs SSH private repo는 SSH 권장
Poetry 2.x에서 git dep 위치 [project.dependencies]에 PEP 508 형식으로
[tool.poetry.dependencies] 사용 시 lock 파일에 반영 안 됨 (함정)
브랜치/커밋 고정 @브랜치명 또는 @커밋해시
전환 전략 local path → git URL 단계적 전환

다음 블로그에서는 SSH 인증 설정과 multi-account GitHub 환경에서의 config alias 문제를 다룬다.

Subscribe

Enjoy this blog? Get notified of new posts by email: