개발 디렉토리를 pip package로 설치하기 - pip install -e .

0. pyproject.toml 과 pip install -e . 사용 튜토리얼

이 글은 개발 중인 Python code directory를 pip package로 install하는 방법을 정리함.

• pyproject.toml을 이용한 package metadata 정의 와
• pip install -e .를 활용한 editable install workflow를
• conda virtual environment 기반 튜토리얼로 설명함.

TOML = Tom’s Obvious, Minimal Language

- 설정(configuration) 파일을 작성하기 위한 language임
- 사람이 읽고 쓰기 쉽도록 설계되었음
- JSON보다 명확하고, YAML보다 단순함을 목표로 함

 

https://dsaint31.tistory.com/534

[Python] pip 란 (Package Management System)

 

---

1. 문제 상황 정리

Python code 작성 후 직접 작성한 코드(예를 들어 my_module.py)에 대해 import 수행 시 다음 오류가 발생하는 경우가 있음.

ModuleNotFoundError: No module named 'my_module'

 

이는 Python이 해당 module의 위치를 알지 못하기 때문임.
Python은 module search path에 등록된 location만을 대상으로 import를 수행함.

 

module search path에 대한 자세한 내용은 다음을 참고: https://dsaint31.tistory.com/528

[Python] Module Search Path and sys.path

---

2. Python의 module search path 구성

Python interpreter는 다음 경로를 순서대로 탐색함.

1. 현재 실행 중인 script directory 
2. site-packages directory
3. PYTHONPATH environment variable에 등록된 경로

User가 작성한 code directory 는 기본적으로 위 경로에 포함되지 않음.

• 단, 같은 경로(개발 디렉토리)에서 실행하는 경우는 1번 덕분에 import 됨.
• 다른 위치에서는 별도 조치 없이는 import 불가함.

---

3. module search path를 직접 조작하는 방법

다음과 같이 module search path를 직접 수정하는 것이 가능함.

import sys
sys.path.append("..")

 

또는 PYTHONPATH environment variable 설정 방식 사용 가능함.

 

이들 방법은 기술적으로 유효한 방법 이며 가장 많이 사용되는 방식임.

다음 이유로 개발환경 에선 불편한 점이 있음.

• 실행 환경에 따라 behavior 달라질 수 있음
• Colab / server / Docker / deployment 환경에서 재현성 저하
• project 규모 증가 시 관리 어려움 증가

Temporary debugging 목적 외에는 사용하지 않는 것이 바람직함.

---

4. 권장되는 해결 방법

권장되는 해결 방법은 user code를 Python package로 install하는 것임.

이 방법을 이 문서에서 소개하고자 함.

 

Package로 install된 code는 site-packages에 등록되며,
모든 execution environment에서 동일한 import behavior를 보장함.

---

5. pip의 역할

pip는 Python package installer임.

pip install numpy

위의 명령은 numpy package를 site-packages에 install함.
이후 Python interpreter는 numpy를 공식 package로 인식하고 사용자는 import numpy가 가능해짐.

---

6. user code만으론 install할 수 없는 이유: pyproject.toml 파일이 필요한 이유.

User code directory에는 설치를 위한 install metadata 가 존재하지 않음.

• pip는 install rule이 정의되지 않은 directory를 package로 인식하지 않음.
• pip가 설치할 수 있도록 metadata를 제공해줘야 함!

---

7. pyproject.toml의 역할

pyproject.toml은 Python package installation metadata를 정의하는 표준 파일임.

다음과 같은 정보를 포함함.

• package name
• version
• required Python version
• dependencies
• build system

과거엔 setup.py, setup.cfg 등을 이용하여
package metadata를 정의했으나
최근 pip는 pyproject.toml을 사용함.

---

8. pyproject.toml 간단 예제

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

[project]
name = "my_pkg"
version = "0.1.0"
requires-python = ">=3.10"

dependencies = [
    "numpy",
]

• 해당 file이 프로젝트의 루트 디렉토리에 존재할 경우,
• pip는 해당 directory를 installable package로 인식함.

 

setuptools는 Python package를 build하고 install하기 위한 도구임.

wheel은 Python package의 binary distribution format 으로 파일 확장자는 .whl임.

 

setuptools.build_meta는 setuptools가 제공하는
PEP 517 build backend implementation임.

역할은 다음과 같음.

• setuptools 기반 project를
• PEP 517 표준 방식으로 build 가능하게 함
• setup.py를 직접 실행하지 않도록 함

---

9. 권장 directory structure

my_project/
├─ pyproject.toml
└─ src/
   └─ my_pkg/
      ├─ __init__.py
      └─ core.py

• src/ layout 사용이 권장됨 (거의 필수 사항).
• 이는 local directory가 우연히 module search path에 포함되는 문제를 방지함.

---

10. pyporoject.toml이 있는 위치에서 pip install . 의 동작 방식

pip install .

• package code를 site-packages로 copy함
• 만약 code가 수정될 경우엔 reinstall 필요 함
• 때문에 development 단계에서는 비효율적임

---

11. pyporoject.toml이 있는 위치에서 pip install -e . 의 동작 방식

pip install -e .

• original directory를 그대로 reference함
• code modification 즉시 반영됨: live update 가 가능함.
• development workflow에 적합함

-e option은 editable install을 의미함.

---

12. installation 방식 비교

항목	pip install .	pip install -e .
code copy	O	X
live update	X	O
development suitability	낮음	높음

---

13. editable install 사용 시 주의사항

• Conda environment와 같은 virtual environment 에서 사용하길 권장!
• 가급적 system Python environment에 직접 install하지 말 것.
• distribution 목적일 경우엔 wheel build 필요함

---

14. 실습 튜토리얼 (conda 기반)

14.1 conda environment 생성

conda create -n pkgdev python=3.10
conda activate pkgdev

• conda environment와 같이,
• isolated environment에서 package install 수행하는 것이 바람직함.

---

14.2 project directory 이동

cd my_project

• pyproject.toml이 위치한 directory에서 작업 수행 필요함.
• my_project/가 프로젝트 루트 디렉토리이며, pyproject.toml이 위치함.

이후 나오는 path는 my_project/ 밑에서 출발함.

---

14.3 editable install 수행

pip install -e .

이후 다음 명령으로 install 여부 확인 가능함.

pip list

---

14.4 example code 작성

# src/my_pkg/core.py
def hello():
    return "hello editable install"

---

14.5 import 확인

from my_pkg.core import hello
print(hello())

• code 수정 후 재실행 시 즉시 반영됨을 확인 가능함.
• live update가 되므로 reinstall 과정 불필요함.

---

15. wheel 빌딩 및 install

15.1 wheel이 필요한 이유

Python package는 기본적으로 source code 형태로 작성됨.
그러나 source code를 그대로 install하는 방식은 다음과 같은 문제가 있음.

• install 시마다 build 과정 필요함
• build 환경에 따라 실패 가능성 존재함
• install 속도가 느림

이를 해결하기 위해 pre-built distribution format이 필요함.
그 결과물이 wheel(.whl) 임.

wheel은 binary extension (C/C++/CUDA 등)을 포함하는 package에서 주로 사용됨.
하지만 pure Python package에도 동일하게 적용 가능함.
PyPI에서 가장 많이 사용되는 공개 배포 방식이나,
Hugging Face Hub등에서는 wheel upload를 필수로 요구하지 않음.

---

15.2 wheel의 정의

wheel은 Python package의 binary distribution format임: 확장자는 .whl임.

wheel은 다음 특징을 가짐.

• install 시 build 과정 생략 가능함
• pip가 바로 unpack하여 install 가능함
• 배포 및 재현성 측면에서 안정적임

즉, wheel은 “install ready artifact” 임.

 

source distribution 로도 배포가 가능한데 이 경우 wheel과의 차이는 다음과 같음:

	source distribution (sdist)	wheel
파일 형태	.tar.gz / .zip	.whl
build 필요 여부	필요함	필요없음
install 속도	느림	빠름
환경 의존성	높은	낮은

---

15.3 wheel packaging workflow 개요

wheel packaging은 다음 단계로 구성됨.

1. project source 준비
2. package metadata 정의
3. wheel build 수행
4. wheel artifact 생성
5. wheel 배포 또는 install

---

15.4 사전 조건

다음 조건이 충족되어야 함.

• pyproject.toml 존재함
• [build-system] section 정의됨
• build backend 설정됨

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

---

15.5 wheel build 수행

wheel build는 다음 명령으로 수행함.

python -m build

해당 명령은 내부적으로 다음 작업을 수행함.

• sdist 생성
• wheel 생성

결과물은 dist/ directory에 저장됨.

dist/
├─ my_pkg-0.1.0-py3-none-any.whl
└─ my_pkg-0.1.0.tar.gz

---

15.6 wheel 파일명 구조

wheel filename은 다음 정보를 포함함.

{distribution}-{version}-{python tag}-{abi tag}-{platform tag}.whl

다음의 예를 참고

my_pkg-0.1.0-py3-none-any.whl

의미는 다음과 같음.

• py3: Python 3 compatible
• none: ABI independent
• any: OS independent

pure Python package의 전형적인 형태

---

15.7 wheel install 과정

wheel install은 다음과 같이 수행함.

pip install dist/my_pkg-0.1.0-py3-none-any.whl

이 경우:

• build 과정 없이 즉시 install됨
• source tree 필요 없음
• install 결과가 deterministic함

---

15.8 wheel 배포 방식

wheel 배포는 다음 방식이 있음.

 

PyPI 배포

• 일반적인 Python package 공개 배포 방식
• pip install package-name으로 install 가능

private index 배포

• 사내 registry 사용
• 보안 및 내부 배포 목적

file 기반 배포 (15.7 의 내용)

• .whl 파일 직접 전달
• offline environment 배포 가능

---

16. editable install과 wheel의 차이

	editable install	wheel install
목적	development	distribution
live update (코드 수정 반영)	가능	불가
source 필요	낮은	높음

즉,

• development 단계: pip install -e .
• distribution 단계: wheel 사용

으로 구분됨.

---

정리

• Python은 module search path 기반으로 import 수행함
• pip 는 Python package installer임
• pyproject.toml은 package installation metadata임
• development 단계에서는 editable install -e 이 적합함
• conda environment 사용이 안전함
• src/ layout은 import 안정성을 높임: 현재 디렉토리가 module search path에 포함되므로.

---

같이 보면 좋은 자료들

https://dsaint31.tistory.com/528

[Python] Module Search Path and sys.path

2023.06.30 - [Python] - [Python] pip 사용법

[Python] pip 사용법

https://ds31x.tistory.com/376

[Tool] conda 사용법 - Anaconda and Miniconda

---