윈도우 Python 설치 + 환경변수(PATH) 설정 — 'python' 명령어 인식 안 될 때

·#Python #환경변수 #PATH #pip #Windows

Java Spring Boot 프로젝트만 하다 Python으로 개발할 일이 생겼다. 이 글에서는 윈도우에서 Python 관련 환경변수를 설정하고, 필요한 라이브러리·패키지를 설치하며 파이썬의 패키지 구조를 알아본다. (Linux는 이후 별도 글로.)

파이썬 설치 (Installation of Python)

파이썬 공식 홈페이지 python.org에서 설치 파일을 받는다.

Python 공식 홈페이지의 버전 선택 화면 그림 1. 파이썬 버전 선택 (2024-10-13 기준)

당시 security 기준 최신이던 3.11 버전을 골라 윈도우 D드라이브에 설치했다.

Python 설치 실행 파일(exe) 그림 2. 파이썬 설치 파일 (exe)

설치 시 Customize Installation을 선택해 설치 경로를 D:\Python으로 지정했다. (경로는 원하는 대로 설정하면 된다.)

Python 설치 경로(D:\Python)의 디렉터리 구조 그림 3. Python 설치 시 디렉터리 파일

파이썬 환경변수 설정 (Environment Variable)

1. 환경 변수 설정이란?

환경 변수 설정은 운영체제(OS)에 프로그램 경로·전역 설정·시스템 구성 정보를 제공해, 애플리케이션이나 명령어가 이를 참조하도록 하는 과정이다.

Java·Python 같은 언어에서 환경 변수를 설정하는 이유는, 컴파일러나 인터프리터 실행 파일을 절대 경로가 아닌 프로그램 이름만으로 실행하기 위함이다. 예를 들어 python.exe를 실행하려면 cmd에서 D:\Python\python.exe 절대 경로를 입력해야 하는데, 매번 그러기는 불편하므로 OS에 경로를 알려줘 python만 입력해도 실행되게 한다. (Windows뿐 아니라 Linux에서도 동일한 개념이다.)

환경변수 설정 없이 python 입력 시 Microsoft Store가 열리는 화면 그림 4. 환경변수 설정 없이 python 명령어 수행

그림 4는 환경 변수를 설정하지 않고 python을 입력했을 때 인식하지 못해 Microsoft Store가 열리는 상황이다. (원래는 "경로를 찾을 수 없다"는 메시지가 뜨지만, PC 설정에 따라 이렇게 연결되기도 한다.)

절대 경로 D:\Python\python.exe 입력 시 Python이 실행되는 화면 그림 5. 절대 경로를 입력했을 때

그림 5처럼 절대 경로 D:\Python\python.exe를 입력하면 Python이 실행된다. 이제 OS에 이 경로를 알려줘 python만 입력해도 실행되게 설정한다.

2. 환경 변수 설정 과정 (Windows 기준)

시스템 환경 변수 편집 검색 그림 6. 시스템 환경 변수 편집

  1. 그림 6처럼 '찾기'에서 '시스템 환경 변수 편집'을 검색하거나
  2. 제어판 → 시스템 및 보안 → 시스템 → 고급 시스템 설정

시스템 속성 창의 환경 변수 버튼 그림 7. 시스템 환경 변수 편집 창

위 방법을 따르면 그림 7 창이 나오는데, 여기서 환경 변수(N)를 클릭한다.

사용자 변수와 시스템 변수로 나뉜 환경 변수 창 그림 8. 환경 변수 창

그림 8처럼 환경 변수 창은 사용자 변수(U)와 시스템 변수(S)로 나뉜다. 둘의 차이는 적용 범위다.

  • USER 변수 — 현재 사용자에게만 적용. 사용자마다 자신만의 변수를 가지며 다른 사용자에게 영향 없음.
  • SYSTEM 변수 — 모든 사용자에게 적용. 시스템 전체에서 사용 가능.

여기서는 모든 사용자에게 적용되도록 시스템 변수에서 설정한다.

시스템 변수의 Path 선택 및 편집 그림 9. 시스템 변수 Path 설정

시스템 변수(S)에서 Path를 더블 클릭하거나 선택 후 편집(I)을 누른다.

Path 편집 창에서 새 경로 추가 그림 10. Python 경로 추가

그림 10에서 새로 만들기(N)를 누르면 경로를 입력할 수 있다. Python 환경변수는 두 경로를 추가해야 한다.

추가해야 할 Python 경로 두 가지 그림 11. 추가해야 할 경로 2가지

  1. D:\Python — python.exe 파이썬 실행 파일이 설치된 경로
  2. D:\Python\Scripts — pip.exe·pip3.exe 등 패키지 관리자가 설치된 경로

(경로는 본인 설치 위치에 따라 다르지만, 설치 경로 아래 python.exe가 있고 Scripts 디렉터리 안에 pip이 있는 구조는 동일하다.)

💡 pip — 파이썬 공식 패키지 관리자. numpy·scipy·pandas·tensorflow 등을 pip install로 받게 해준다. JavaScript의 npm, Java의 Maven·Gradle 의존성 관리와 비슷한 역할이다.

3. 환경 변수 설정 결과

두 경로를 추가해 적용하면 Python 환경 변수 설정이 끝난다.

cmd에서 python과 pip 명령어가 정상 동작하는 화면 그림 12. 환경변수 설정 결과

그림 12처럼 cmd에서 python을 입력했을 때 Python이 실행되고, pip을 입력했을 때 패키지 관리자 설명이 나오면 정상이다.

4. pip으로 설치한 라이브러리의 디렉터리 구조

pip3 install로 numpy·pandas 같은 라이브러리를 설치해 보자.

pip으로 pandas를 설치하는 화면 그림 13. pip을 통해 pandas 설치

이렇게 설치한 라이브러리는 기본적으로 D:\Python\Lib\site-packages에 저장된다. 그림 3에서 봤듯 Python 설치 경로에 Lib 디렉터리가 있고, 그 안에 site-packages 폴더가 있다.

site-packages에 설치된 numpy·pandas 라이브러리 그림 14. pip로 설치한 라이브러리의 저장 경로

그림 14에서 site-packages 안에 pip으로 설치된 numpy·pandas 등을 확인할 수 있다.

이렇게 pip으로 설치한 라이브러리와 버전을 관리하면 라이브러리 간 충돌을 방지하고 체계적으로 운영할 수 있다.

환경변수 설정이 끝났다면, 이제 FastAPI를 설치하고 첫 서버를 띄워볼 차례다.

Python FastAPI 시작하기 — 개론·설치·Pycharm 실행 (feat. uvicorn)
FastAPI를 쓰는 이유(비동기·I/O bound)와 Python GIL의 관계, pip로 FastAPI·uvicorn 설치, 웹 프레임워크와 웹 애플리케이션(ASGI/WSGI)의 관계, Pycharm에서 uvicorn으로 서버를 실행하는 두 가지 방법과 내장 Swagger-UI까지 정리한 FastAPI 입문 가이드.
taystudios.com/blog

📦 이 글은 제가 운영하던 티스토리 블로그에서 옮겨온(migration) 글입니다. 원문: taehyuklee.tistory.com/20

관련 글

이 글 공유𝕏f

댓글