setup.py로 파이썬 프로젝트를 설치 가능한 패키지로 만드는 방법

📦 setup.py란 무엇인가요?

setup.py는 파이썬 프로젝트를 설치 가능한 패키지로 만들기 위해 사용하는 설정 파일입니다.
이 파일은 setuptools 또는 distutils와 함께 사용되며, 프로젝트를 배포하거나 pip install로 설치할 수 있도록 만들어주는 핵심 역할을 합니다.

setup.py는 단순히 패키지를 설치하는 것을 넘어, 프로젝트의 이름, 버전, 설명, 라이선스, 작성자, 의존성 등 다양한 정보를 명시할 수 있습니다.
이 정보는 PyPI(Python Package Index)에 업로드할 때도 활용되며, 다른 개발자들이 패키지를 이해하고 활용하는 데 큰 도움이 됩니다.

• 📁프로젝트의 메타 정보 저장
• 🔧패키지 설치 방식 정의 가능
• 🚀pip install로 설치 가능한 구조 생성

💬 setup.py 파일이 있어야만 pip 명령어를 통해 로컬 패키지를 설치하거나, PyPI에 배포할 수 있습니다.

📝 setup.py 기본 구조와 필수 항목

setup.py 파일은 setuptools.setup() 함수를 통해 패키지의 설정을 정의합니다.
아래는 가장 기본적인 형태의 setup.py 예제이며, 실제 배포에 필요한 필수 항목들로 구성되어 있습니다.

📌 기본 예제 코드

from setuptools import setup, find_packages

setup(
    name="my_package",
    version="0.1.0",
    description="예제 패키지입니다",
    author="홍길동",
    author_email="hong@example.com",
    packages=find_packages(),
    install_requires=[
        "requests>=2.0.0",
        "numpy==1.24.3"
    ],
)

📌 주요 항목 설명

🔧 배포 가능한 패키지 만들기

setup.py를 기반으로 하면 자신의 프로젝트를 누구나 설치 가능한 패키지로 만들 수 있습니다.
이를 위해서는 몇 가지 폴더 구조와 빌드 명령을 이해하고 있어야 하며, Python Packaging Authority(PyPA)의 권장 방식에 따라 진행하는 것이 좋습니다.

패키징 작업은 단순히 파일을 압축하는 것이 아니라, 설치 가능한 메타 정보가 포함된 압축 파일(.whl, .tar.gz)을 만드는 과정입니다.
이 과정을 통해 pip install로 설치하거나, PyPI 업로드가 가능한 상태로 만들 수 있습니다.

📌 패키징 절차

• 📂setup.py가 포함된 루트 디렉토리 구성
• 🛠️필요 시 README.md, LICENSE, MANIFEST.in 추가
• 📦python setup.py sdist bdist_wheel 명령어 실행

📌 dist 디렉토리에 생성된 결과물

위 명령어를 실행하면 dist/ 폴더가 생성되고, 그 안에 .tar.gz(소스 배포용)와 .whl(바이너리 배포용) 파일이 생성됩니다.
이 파일들이 실제로 pip install로 설치 가능한 배포 패키지입니다.

python setup.py sdist bdist_wheel

🚀 pip로 설치 가능한 구조 만들기

setup.py를 기반으로 빌드한 패키지는 pip를 사용하여 로컬에서도 설치할 수 있으며, PyPI에 업로드하면 전 세계 누구나 pip install 명령어로 간편하게 설치할 수 있습니다.
이를 위해서는 몇 가지 디렉터리 규칙과 설치 가능한 구조를 갖추는 것이 중요합니다.

📌 pip로 로컬 설치하기

setup.py가 포함된 루트 디렉터리에서 다음 명령어를 입력하면 현재 환경에 패키지가 설치됩니다.

pip install .

또는 아카이브 파일을 직접 설치하고 싶다면, dist 폴더 내 파일명을 지정해서 설치할 수 있습니다.

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

📌 설치 가능한 구조 예시

pip 설치를 위해서는 다음과 같은 디렉터리 구조가 일반적입니다.

my_project/
├── my_package/
│   └── __init__.py
├── setup.py
├── README.md
└── requirements.txt

⚠️ 자주 하는 실수와 해결 방법

setup.py로 패키징을 처음 시도할 때는 사소한 실수 하나로 빌드 오류나 설치 실패가 발생하는 경우가 많습니다.
아래는 많은 개발자들이 경험하는 대표적인 실수들과 그에 대한 해결 방법을 정리했습니다.

📌 실수와 원인

• ❌패키지 구조 누락으로 인해 find_packages()가 폴더를 인식하지 못함
• 📝__init__.py 누락으로 인해 Python 패키지로 인식되지 않음
• 📦dist 폴더 삭제 없이 재패키징하여 오래된 파일로 설치됨
• 🔐PyPI 배포 시 버전 중복으로 업로드 실패

📌 해결 방법

위와 같은 문제를 예방하려면 다음 사항을 체크하세요.

❓ 자주 묻는 질문 (FAQ)