pip install -e란 무엇인가? (egg-info 폴더, 배포 이름 vs import 이름까지)

pip install -e .를 처음 마주치면 이런 생각이 듭니다.

• “왜 굳이 -e를 붙이지?”
• “*.egg-info/는 뭐지? 왜 갑자기 생겼지?”
• “pyproject.toml의 name이랑 import는 같은 거 아냐?”

나도 처음에 여기서 한번씩 멈췄는데, 딱 헷갈리는 포인트만 정리해본다.

한 줄 요약

pip install -e .는 현재 디렉터리(.)의 프로젝트를 editable(편집 가능) 모드로 설치해서, 코드를 수정해도 재설치 없이 바로 import 결과에 반영되게 해주는 개발용 설치 방식이다.

pip install .는 현재 디렉터리의 프로젝트를 일반 설치(non-editable) 하는 명령이라, 설치 이후에 로컬 소스를 수정해도 변경이 즉시 반영되지 않을 수 있다.

1) pip install -e .가 실제로 하는 일

1-1) 일반 설치(pip install .)와 차이

• 일반 설치(pip install .)

  • 프로젝트 소스를 빌드/복사해서 보통 site-packages 아래에 설치된다.
  • 설치 이후에 내 작업 폴더의 코드를 수정해도 “설치된 결과물”은 그대로라, 변경이 즉시 반영되지 않을 수 있습니다.

• editable 설치(pip install -e .)

  • 소스를 복사해 넣기보다, 현재 작업 폴더를 가리키도록 연결해서 “설치된 패키지처럼” 동작하게 합니다.
  • 그래서 코드 수정이 즉시 import 결과에 반영됩니다.
  • 즉, -e는 개발할 때 “수정 → 재설치” 루프를 없애는 옵션입니다.

개발용 의존성까지 같이 설치하려면 pyproject.toml의 **[project.optional-dependencies]**에 정의된 그룹 이름(extras) 을 선택해서 설치하며 대괄호 안에 해당 이름을 넣어 주면 된다

pip install -e ".[dev]"

• .[dev]의 의미: 현재 프로젝트(.) + dev extra(개발용 추가 의존성: pytest/ruff/black 등) 를 함께 설치
• 따옴표는 쉘에서 []를 안전하게 처리하려고 붙이는 습관이며 붙이는 걸 권장

1-2) 언제 쓰는 게 맞나?

• 로컬에서 서비스를/라이브러리를 개발하면서 import를 “설치된 패키지처럼” 쓰고 싶을 때
• 테스트, 서버 실행, 스크립트 등 여러 진입점에서 같은 import 경로를 유지하고 싶을 때
• 개발 중에 매번 pip install .을 반복하고 싶지 않을 때

1-3) 어느 파일을 로드 하는지?

pip install .(또는 pip install -e .)을 치면 pip은 현재 폴더(.) 를 “파이썬 프로젝트”로 보고, 아래 중 하나를 찾는다.

• pyproject.toml: 요즘 표준. 있으면 이걸 기준으로 빌드/설치를 진행한다.
• setup.py: 예전 방식(레거시). pyproject.toml이 없을 때 이걸 보고 설치한다.

pyproject.toml에서 include = ["app*"]로 잡혀 있어서 app/이 설치 대상으로 들어간다.
그래서 설치 후에는 보통 from app... 형태로 import 하게 된다.

2) *.egg-info/는 뭐고 왜 생기나?

2-1) 정체: 설치/패키징 메타데이터

.egg-info 폴더는 파이썬 패키징 도구가 생성하는 메타데이터(설치 정보) 입니다.
pip은 이 프로젝트가 어떤 패키지인지(이름/버전/의존성)를 알아야 설치와 의존성 해결을 할 수 있으며,
그 정보를 기록하기 위해 egg-info(또는 경우에 따라 dist-info)가 생성됩니다.

보통 .gitignore에 추가 하여 관리 한다.

폴더 안 구조(뭐가 들어있나)

프로젝트마다 100% 똑같진 않지만, *.egg-info/ 안에는 보통 이런 파일들이 들어간다. (내가 실제로 많이 본 것들 기준)

• PKG-INFO
  • 패키지 메타데이터가 들어간다.
  • 예: 이름(name), 버전(version), 요약(description) 같은 값들이 여기 들어간다.
• requires.txt
  • “이 패키지를 설치할 때 같이 깔아야 하는 의존성” 목록이 들어간다.
  • pyproject.toml의 dependencies나 extras 내용이 설치 도구에 의해 여기로 정리되는 느낌이라고 보면 된다.
• SOURCES.txt
  • 배포/설치에 포함되는 파일 목록이 들어간다.
  • “패키지 만들 때 어떤 파일들이 패키지에 포함되는지”를 추적하는 용도라서, 설치 방식/설정에 따라 내용이 달라질 수 있다.
• top_level.txt
  • 최상위 import 패키지 이름이 들어간다.
  • 예: app 같은 최상위 패키지명이 여기 적혀 있을 수 있다.
• dependency_links.txt (가끔 비어있기도 함)
  • 예전 방식/특수한 의존성 링크가 기록되는 파일인데, 요즘 일반적인 프로젝트에서는 비어있는 경우가 많다.

중요한 건, 이 폴더는 “내 앱 코드”가 아니라 설치/패키징을 위한 기록물이라서 보통 직접 손댈 일이 거의 없다.

3) “배포 이름”과 “import 이름”은 다르다

여기서 많이 헷갈리는데, 결론부터 말하면 이 둘은 역할이 다르다.

• 배포 이름: pip install ... 할 때 쓰는 이름
• import 이름: 파이썬 코드에서 import ... 할 때 쓰는 이름(폴더/파일 이름)

3-1) 배포 이름(distribution name)

pyproject.toml의 name이 배포 이름이다.

[project]
name = "python_backend"

# 이 이름은 주로 패키지 명에 사용 된다
pip install python_backend
pip uninstall python_backend
pip list
pip show python_backend

3-2) import 이름(module/package name)

import는 파이썬이 찾는 모듈/패키지 이름(폴더/파일 이름) 을 쓴다.

최상위 패키지가 app/이면 import는 보통 이렇게 한다.

from app.main import app

배포 이름과 import의 차이 떄문에 보통 name과 import할 최상위 패키지 폴더명을 일치시킵니다.

4) 결론

• pip install -e .는 개발 편의를 위해 내 작업 폴더를 “설치된 것처럼” 연결해줍니다.
• *.egg-info/는 그 과정에서 만들어지는 설치 메타데이터입니다.
• pyproject.toml의 name은 배포 이름, import는 패키지 폴더 이름입니다.