스마트플렉스

독립적인 파이썬(Python) 환경을 구축

09.08.2025 DevKim

이번 가이드에서는 Windows 11 환경에서 특정 프로젝트에 종속된 독립적인 파이썬(Python) 환경을 구축하는 방법을 다룹니다. 시스템에 영향을 주지 않는 ‘포터블(Portable)’ 파이썬 환경을 구성하고, 이를 위한 환경 변수 설정 및 테스트 절차를 체계적으로 안내합니다.

도입 (Introduction)

일반적인 파이썬 설치 프로그램은 시스템 전역에 파이썬을 설치하여 모든 프로젝트가 동일한 실행 파일을 공유하게 합니다. 이는 프로젝트별로 다른 버전의 파이썬이나 라이브러리 의존성이 필요할 때 충돌을 일으키는 원인이 될 수 있습니다.

이 가이드의 목표(Goal)는 파이썬 공식 **임베디드 패키지(Embeddable Package, 특정 환경에 독립적으로 실행될 수 있도록 압축된 파이썬 배포판)**를 사용하여 특정 프로젝트 폴더 내부에 완벽하게 격리된 파이썬 환경을 구축하는 것입니다.

최종 상태(End State)는 사용자가 생성한 특정 프로젝트 폴더가 그 자체로 완전한 파이썬 실행 환경을 갖추게 되어, 다른 시스템이나 프로젝트와 완벽하게 분리되어 동작하는 것입니다. 이 환경은 폴더를 복사하는 것만으로 다른 PC에서도 동일하게 작동할 수 있습니다.

사전 준비 사항 (Prerequisites)

가이드를 시작하기 전, 다음 사항을 확인하십시오.

  • 운영체제: Windows 11
  • 소프트웨어:
    • 웹 브라우저 (파이썬 다운로드용)
    • 텍스트 편집기 (예: 메모장, Visual Studio Code)
  • 권한: 파일 및 폴더를 생성하고 수정할 수 있는 사용자 권한. (관리자 권한은 필요하지 않습니다.)
  • 지식: 파일 경로 및 디렉터리 구조에 대한 기본적인 이해.

단계별 절차 (Step-by-Step Guide)

1단계: 파이썬 임베디드 패키지 다운로드 및 압축 해제

  • 목표 : 프로젝트의 기반이 될 이식 가능한 파이썬 압축 파일을 확보하고, 프로젝트 폴더 내에 배치합니다.
  • 이유 : 표준 설치 프로그램(.exe)은 시스템 레지스트리를 수정하고 여러 디렉터리에 파일을 분산시킵니다. 반면, 임베디드 패키지는 단일 폴더 내에서 독립적으로 실행되도록 설계되어 완벽한 이식성과 격리성을 보장합니다.
  1. Python 공식 웹사이트의 Windows 다운로드 페이지로 이동합니다.
  2. 안정적인 최신 버전(Stable Releases) 목록에서 **”Windows embeddable package (64-bit)”**를 찾아 다운로드합니다. 이 가이드에서는 Python 3.12.3 버전을 기준으로 설명합니다.
  3. 파이썬 환경을 구축할 프로젝트 폴더를 생성합니다. 예를 들어, C:\dev\my-isolated-project 경로에 폴더를 생성합니다.
  4. 다운로드한 .zip 압축 파일의 내용물 전체를 방금 생성한 프로젝트 폴더 내부에 python이라는 이름의 하위 폴더를 만들어 압축을 해제합니다.
    • 최종 경로 예시: C:\dev\my-isolated-project\python\

검증:
C:\dev\my-isolated-project\python\ 폴더 내에 python.exe, python312.dll과 같은 파일들이 존재하는지 확인합니다.

2단계: Pip 설치 기능 활성화

  • 목표 : 임베디드 패키지에서 기본적으로 비활성화된 pip(파이썬 패키지 관리자)를 사용할 수 있도록 설정을 변경합니다.
  • 이유 : 임베디드 패키지는 최소한의 실행 환경을 제공하기 위해 패키지 설치 경로 탐색 기능이 꺼져 있습니다. pythonXX._pth 파일의 주석을 제거하여 site-packages 디렉터리를 활성화해야 pip가 정상적으로 동작합니다.
  1. 1단계에서 압축 해제한 python 폴더로 이동합니다. (C:\dev\my-isolated-project\python\)
  2. python312._pth 와 같이 python[버전]._pth 형식의 파일을 텍스트 편집기로 엽니다.
  3. 파일 내용 중 #import site 로 주석 처리된 부분을 찾아 맨 앞의 # 기호를 삭제합니다.수정 전: code Codedownloadcontent_copyexpand_less python312.zip . # Uncomment to run site.main() automatically #import site 수정 후: code Codedownloadcontent_copyexpand_lessIGNORE_WHEN_COPYING_STARTIGNORE_WHEN_COPYING_END python312.zip . # Uncomment to run site.main() automatically import site
  4. 파일을 저장하고 닫습니다.

검증:
명령 프롬프트(CMD)를 열고 다음 명령어를 실행하여 pip를 설치합니다. pip가 정상적으로 설치되면 설정이 올바르게 완료된 것입니다.

참고: 아래 명령어는 [YOUR_PROJECT_PATH] 부분을 실제 프로젝트 경로로 변경하여 실행해야 합니다.

code Cmddownloadcontent_copyexpand_less

IGNORE_WHEN_COPYING_START

IGNORE_WHEN_COPYING_END

curl https://bootstrap.pypa.io/get-pip.py -o C:\dev\my-isolated-project\get-pip.py
C:\dev\my-isolated-project\python\python.exe C:\dev\my-isolated-project\get-pip.py

설치가 완료된 후 C:\dev\my-isolated-project\python\Scripts 폴더 내에 pip.exe 파일이 생성되었는지 확인합니다.

3단계: 프로젝트 전용 환경 변수 스크립트 작성

  • 목표 : 현재 프로젝트 폴더 내에서만 python과 pip 명령어를 직접 사용할 수 있도록 경로를 설정하는 배치 스크립트(.bat)를 생성합니다.
  • 이유 : 시스템의 전역 PATH 환경 변수를 수정하는 것은 다른 프로그램에 예기치 않은 영향을 줄 수 있습니다. 프로젝트 폴더 내에 활성화 스크립트를 두면, 필요할 때만 해당 프로젝트의 파이썬 경로를 임시로 추가하여 안전하고 독립적인 작업 환경을 보장할 수 있습니다.
  1. 프로젝트의 최상위 폴더(C:\dev\my-isolated-project\)에 텍스트 편집기를 사용하여 activate.bat 라는 이름의 새 파일을 생성합니다.
  2. activate.bat 파일에 다음 내용을 작성하고 저장합니다. code Batdownloadcontent_copyexpand_lessIGNORE_WHEN_COPYING_STARTIGNORE_WHEN_COPYING_END @echo off set "PATH=%CD%\python;%CD%\python\Scripts;%PATH%" echo Portable Python environment is activated. echo. echo Python Path: %CD%\python echo Pip Path: %CD%\python\Scripts echo.설명:
    • @echo off: 명령어 실행 시 터미널에 명령어가 표시되지 않도록 합니다.
    • set “PATH=…”: 현재 터미널 세션의 PATH 환경 변수를 재설정합니다.
    • %CD%: 현재 작업 디렉터리(Current Directory)를 의미하는 변수로, 이 스크립트가 어디서 실행되든 항상 올바른 상대 경로를 참조하게 만듭니다.
    • %CD%\python 및 %CD%\python\Scripts: 우리가 설치한 포터블 파이썬과 pip의 경로를 PATH의 가장 앞에 추가하여, 시스템에 다른 파이썬이 설치되어 있더라도 이들을 먼저 찾게 합니다.

검증:
파일 탐색기에서 C:\dev\my-isolated-project 폴더로 이동한 후, 주소창에 cmd를 입력하고 Enter를 눌러 해당 경로에서 명령 프롬프트를 엽니다. 터미널에서 activate.bat를 실행했을 때, 아래와 유사한 메시지가 출력되는지 확인합니다. code Cmddownloadcontent_copyexpand_less

IGNORE_WHEN_COPYING_START

IGNORE_WHEN_COPYING_END

      C:\dev\my-isolated-project>activate.bat
Portable Python environment is activated.

Python Path: C:\dev\my-isolated-project\python
Pip Path:    C:\dev\my-isolated-project\python\Scripts

4단계: 포터블 환경 테스트

  • 목표 : 활성화된 환경에서 파이썬 인터프리터, 패키지 설치(pip), 그리고 실제 코드 실행이 모두 정상적으로 동작하는지 최종 확인합니다.
  • 이유 : 모든 구성 요소가 올바르게 연결되었는지 실증적인 테스트를 통해 검증함으로써, 향후 개발 과정에서 발생할 수 있는 환경 문제를 사전에 차단합니다.
  1. activate.bat 스크립트가 실행된 터미널에서 다음 명령어들을 순서대로 입력하여 파이썬과 pip가 올바른 경로에서 실행되는지 확인합니다. code Cmddownloadcontent_copyexpand_lessIGNORE_WHEN_COPYING_STARTIGNORE_WHEN_COPYING_END where python where pip 출력되는 경로가 C:\dev\my-isolated-project\python\으로 시작해야 합니다.
  2. pip를 사용하여 외부 패키지(requests)를 설치합니다. code Cmddownloadcontent_copyexpand_lessIGNORE_WHEN_COPYING_STARTIGNORE_WHEN_COPYING_END pip install requests “Successfully installed…” 메시지가 나타나면 성공입니다.
  3. 프로젝트 폴더(C:\dev\my-isolated-project\)에 test.py 파일을 생성하고 다음 코드를 작성합니다. code Pythondownloadcontent_copyexpand_lessIGNORE_WHEN_COPYING_STARTIGNORE_WHEN_COPYING_END import requests try: response = requests.get("https://www.google.com") print(f"Connection successful. Status code: {response.status_code}") except requests.exceptions.RequestException as e: print(f"Connection failed: {e}")
  4. 터미널에서 파이썬 스크립트를 실행합니다. code Cmddownloadcontent_copyexpand_lessIGNORE_WHEN_COPYING_STARTIGNORE_WHEN_COPYING_END python test.py

검증:
터미널에 다음과 같은 성공 메시지가 출력되면, 모든 설정이 성공적으로 완료된 것입니다. code Codedownloadcontent_copyexpand_less

IGNORE_WHEN_COPYING_START

IGNORE_WHEN_COPYING_END

      Connection successful. Status code: 200

결론 및 다음 단계 (Conclusion & Next Steps)

이번 가이드를 통해 Windows 11 시스템에서 파이썬 임베디드 패키지를 활용하여 완전히 독립된 포터블 파이썬 환경을 구축했습니다. 핵심은 pythonXX._pth 파일을 수정하여 pip를 활성화하고, 시스템 PATH를 건드리지 않는 로컬 활성화 스크립트(activate.bat)를 사용하는 것이었습니다.

습득한 기술적 이점:

  • 프로젝트 격리: 각 프로젝트가 자신만의 파이썬과 라이브러리를 가지므로 버전 충돌 문제가 원천적으로 방지됩니다.
  • 이식성: 프로젝트 폴더 전체를 복사하여 다른 PC로 옮기거나 USB에 담아도 동일한 환경에서 즉시 작업을 이어갈 수 있습니다.
  • 클린 시스템: 시스템 전역에 불필요한 파일이나 레지스트리 항목을 남기지 않습니다.

다음 단계 제안:

  • Visual Studio Code 연동: VS Code의 작업 영역(Workspace) settings.json 파일에 “python.defaultInterpreterPath”: “${workspaceFolder}\\python\\python.exe” 설정을 추가하여, 해당 프로젝트를 열 때마다 자동으로 포터블 파이썬 인터프리터를 인식하도록 설정할 수 있습니다.
  • 가상 환경(venv) 활용: 현재 구성된 포터블 환경 내에서 python -m venv .venv 명령어를 통해 추가적인 가상 환경을 생성하면, 동일한 파이썬 버전 위에서 라이브러리 그룹을 더욱 세분화하여 관리할 수 있습니다.

답글 남기기