스마트플렉스

포터블 파이썬 환경을 Windows 11 시스템의 전역 환경 변수에 등록

09.08.2025 DevKim

Windows 11에서 포터블 파이썬을 시스템에 등록하는 방법

이번 가이드에서는 Windows 11 운영체제에서 포터블 파이썬(Portable Python) 환경을 시스템의 전역 환경 변수(System Environment Variables)에 등록하는 방법을 다룹니다. 이 절차를 통해 시스템의 어떤 위치에서든 python 명령어를 직접 실행할 수 있을 뿐만 아니라, 파이썬이 자신의 표준 라이브러리와 설치된 패키지를 안정적으로 찾도록 설정합니다.

도입 (Introduction)

포터블 파이썬은 시스템에 정식으로 설치하지 않고 특정 폴더에 압축을 풀어 바로 사용할 수 있어 환경 격리에 유리합니다. 하지만 단순히 실행 파일의 경로만 등록하는 것만으로는 부족하며, 파이썬이 자신의 라이브러리 경로를 인식하지 못해 모듈 임포트 시 오류가 발생할 수 있습니다.

  • 목표 (Goal): Windows 11의 Path와 PYTHONPATH 환경 변수를 모두 설정합니다. 이를 통해 모든 터미널에서 python 및 pip를 즉시 실행하고, 파이썬 프로그램이 라이브러리를 문제없이 임포트할 수 있는 완전하고 안정적인 포터블 환경을 구축합니다.
  • 최종 상태 (End State): 어떤 디렉터리에서든 python 명령어를 실행하고, import os와 같은 표준 라이브러리나 pip로 설치한 외부 라이브러리를 오류 없이 가져올(import) 수 있습니다.

사전 준비 사항 (Prerequisites)

이 가이드를 진행하기 전에 다음 항목들이 반드시 준비되어 있어야 합니다.

  • 운영체제: Windows 11
  • 관리자 권한: 시스템 환경 변수를 수정하기 위해 관리자(Administrator) 권한을 가진 계정이 필요합니다.
  • 포터블 파이썬: Python 공식 웹사이트에서 다운로드한 임베디드 패키지(Embeddable Package)의 압축이 해제된 상태여야 합니다. 해당 폴더 내에 python.exe와 Lib 폴더가 존재해야 합니다.
  • 포터블 파이썬 경로: python.exe 파일이 위치한 폴더의 전체 경로를 미리 확인하고 복사해 두어야 합니다. (예: C:\dev\python-3.11-embed)

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

1단계: 포터블 파이썬 경로 확인 및 복사

  • 목표: 시스템 환경 변수에 추가할 포터블 파이썬의 베이스 폴더 절대 경로를 정확히 확인하고 복사합니다.
  • 이유: Path와 PYTHONPATH 두 변수 모두에 정확한 경로를 입력해야 합니다. 오류를 방지하기 위해 이 단계에서 경로를 한 번만 복사하여 재사용합니다.
  1. 파일 탐색기를 열어 포터블 파이썬의 압축을 해제한 폴더로 이동합니다.
  2. 폴더 내에 python.exe 파일이 있는지 확인합니다.
  3. 파일 탐색기의 주소 표시줄을 클릭하여 전체 경로를 블록 지정한 후, Ctrl + C를 눌러 복사합니다. 이 가이드에서는 예시 경로로 C:\dev\python-3.11-embed를 사용하겠습니다.

검증: 복사한 경로를 메모장 등에 붙여넣기하여 C:\dev\python-3.11-embed와 같은 형식의 절대 경로가 올바르게 복사되었는지 확인합니다.

2단계: 시스템 환경 변수 편집기 실행

  • 목표: Windows 11에서 시스템 전체에 영향을 미치는 환경 변수를 수정할 수 있는 설정 창을 엽니다.
  • 이유: 모든 사용자와 모든 터미널에 파이썬 설정을 적용하려면 반드시 ‘시스템 변수’를 수정해야 하며, 이는 관리자 권한이 필요합니다.
  1. 키보드의 Win 키를 누르고 “시스템 환경 변수 편집”이라고 입력합니다.
  2. 검색 결과에 나타난 ‘시스템 환경 변수 편집’ 제어판 항목을 클릭하여 실행합니다.
  3. ‘시스템 속성’ 창에서 환경 변수(N)… 버튼을 클릭합니다.

검증: ‘환경 변수’ 창이 열리고, 상단에는 ‘사용자 변수’, 하단에는 ‘시스템 변수’ 섹션이 표시되는 것을 확인합니다.

3단계: 시스템 ‘Path’ 변수에 실행 경로 추가

  • 목표: 시스템 변수 Path에 python.exe와 pip.exe가 위치할 폴더 경로를 추가하여 터미널에서 명령어를 직접 실행할 수 있도록 합니다.
  • 이유: Path는 운영체제가 명령어의 실행 파일 위치를 검색하는 경로 목록입니다. 여기에 경로를 등록해야 전체 경로 없이 python이라는 이름만으로 실행할 수 있습니다.
  1. ‘시스템 변수’ 섹션에서 Path를 선택하고 편집(E)… 버튼을 클릭합니다.
  2. 새로 만들기(N)를 클릭하고 1단계에서 복사한 경로(예: C:\dev\python-3.11-embed)를 붙여넣습니다.
  3. 다시 새로 만들기(N)를 클릭하고, 이전 경로에 \Scripts를 추가한 경로(예: C:\dev\python-3.11-embed\Scripts)를 입력합니다. Scripts 폴더는 pip를 사용하면 자동으로 생성됩니다.
  4. 확인을 눌러 Path 편집 창을 닫습니다.

검증: ‘환경 변수’ 창으로 돌아온 상태입니다. 아직 최종 확인 버튼을 누르지 마십시오.

4단계: PYTHONPATH 환경 변수 설정 (권장)

  • 목표: 파이썬 인터프리터가 표준 라이브러리와 외부 패키지를 찾을 수 있도록 PYTHONPATH 시스템 변수를 생성하고 경로를 지정합니다.
  • 이유: 정식 설치 버전과 달리 포터블 파이썬은 라이브러리 검색 경로가 자동으로 설정되지 않을 수 있습니다. PYTHONPATH를 명시적으로 지정하면 import 시 발생할 수 있는 ModuleNotFoundError를 근본적으로 방지하여 환경의 안정성을 크게 높입니다.
  1. ‘환경 변수’ 창의 ‘시스템 변수’ 섹션에서 새로 만들기(S)… 버튼을 클릭합니다.
  2. ‘새 시스템 변수’ 창이 나타나면 다음과 같이 입력합니다.
    • 변수 이름(N): PYTHONPATH
    • 변수 값(V): [YOUR_PYTHON_PATH]\Lib;[YOUR_PYTHON_PATH]\Lib\site-packages
      • 1단계에서 복사한 경로를 [YOUR_PYTHON_PATH] 부분에 붙여넣어 완성합니다.
      • 예시: C:\dev\python-3.11-embed\Lib;C:\dev\python-3.11-embed\Lib\site-packages
  3. 확인 버튼을 눌러 새 시스템 변수 등록을 완료합니다.
  4. ‘환경 변수’ 창의 확인 버튼을 누릅니다.
  5. 마지막으로 ‘시스템 속성’ 창의 확인 버튼을 눌러 모든 변경 사항을 시스템에 최종 적용합니다.

검증: PYTHONPATH 변수가 ‘시스템 변수’ 목록에 정상적으로 추가되었는지 육안으로 확인합니다.

5단계: 터미널에서 전체 설정 결과 최종 확인

  • 목표: 새로 적용된 Path와 PYTHONPATH 변수가 모두 올바르게 동작하는지 검증합니다.
  • 이유: 환경 변수 변경 사항은 새로 시작된 터미널 세션에만 적용됩니다. 반드시 새 터미널을 열어 테스트해야 합니다.
  1. 중요: 이전에 열려 있던 모든 터미널 창을 닫습니다.
  2. Win + R을 누르고 cmd를 입력하여 새로운 명령 프롬프트를 엽니다.
  3. 아래의 명령어들을 차례대로 입력하여 결과를 확인합니다.

Path 변수 확인: code Bashdownloadcontent_copyexpand_less

      where python

예상 출력: code Codedownloadcontent_copyexpand_less

      C:\dev\python-3.11-embed\python.exe

PYTHONPATH 변수 확인:
파이썬 인터프리터를 실행합니다. 

      python

파이썬 프롬프트(>>>)가 나타나면, sys 모듈을 임포트하여 파이썬의 실제 검색 경로를 출력합니다.

      import sys
print(sys.path)

예상 출력:
출력된 리스트 안에, 우리가 PYTHONPATH에 추가했던 C:\\dev\\python-3.11-embed\\Lib 와 C:\\dev\\python-3.11-embed\\Lib\\site-packages 경로가 포함되어 있는지 확인합니다. (경로 구분자는 \\로 표시될 수 있습니다)

확인 후 exit()를 입력하여 파이썬 인터프리터를 종료합니다.

검증: where python 명령어가 올바른 경로를 출력하고, sys.path 출력 결과에 PYTHONPATH로 설정한 경로들이 포함되어 있다면 모든 설정이 성공적으로 완료된 것입니다.

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

이번 가이드를 통해 Path와 PYTHONPATH 환경 변수를 모두 설정하여, Windows 11 시스템에서 포터블 파이썬을 위한 매우 안정적이고 완벽한 실행 환경을 구축했습니다. 이제 어떤 위치에서든 파이썬 명령어를 편리하게 실행할 수 있을 뿐만 아니라, 라이브러리 경로 문제로 인한 잠재적 오류로부터 자유로워졌습니다.

이 견고한 기반 위에서 다음과 같은 작업을 안심하고 수행할 수 있습니다.

  • 패키지 관리: pip install numpy pandas와 같이 데이터 분석 및 머신러닝 라이브러리를 설치하고 즉시 코드에서 import 하여 사용합니다.
  • 독립된 프로젝트 환경: python -m venv my_project_env 명령어로 프로젝트별 가상 환경을 생성하여 전역 패키지와 프로젝트별 패키지를 분리, 관리함으로써 의존성 충돌을 방지합니다.

답글 남기기