[venv, pyenv, poetry] 윈도우 파이썬 버전 및 가상환경 툴 설치 및 사용법

pc를 포맷하거나 tool을 설치할 때 매번 잊어먹어서 이참에 정리해둔다.

윈도우에서 사용가능한 파이썬 버전 관리 툴과 가상환경 툴이 많다. 사용해본 툴만 정리하고자 한다.

( pipenv 등 여기서 설명하지 않았지만 다른 도구들도 많은 듯하다.)

 

개발 환경 관리 툴을 세 가지 종류로 나누었다.

1. 파이썬 버전 관리 O, 가상환경 관리 X -> pyenv-win(윈도우용 pyenv)

2. 파이썬 버전 관리 X, 가상환경 관리 O -> venv, pyenv-win-env(pyenv와 같이 쓴다.), poetry

3. 파이썬 버전 관리 O, 가상환경 관리 O -> conda

 

이번 포스팅에서는 conda를 제외한 venv와 pyenv 그리고 poetry의 설치과정을 주로 다루고, 사용법도 간단하게 설명할 예정이다.

 

* venv 모듈 ( 파이썬 버전 관리 X, 가상환경 관리 O )

파이썬에서 표준라이브러리로 제공해주는 가상환경 모듈이다. 가장 보편적으로 사용된다. poetry에서도 venv모듈을 default로 사용하여 가상환경을 설치해주는 기능을 제공한다. (poetry는 conda의 가상환경을 사용할 수도 있다.)

•  장점:
  파이썬이 설치되어있다면 표준라이브러리이기 때문에 따로 설치해줄 필요 없다.
•  단점:
  파이썬 버전을 지정해서 가상환경을 생성할 수 있지만, 미리 해당 파이썬 버전이 설치되어 있어야한다. 윈도우에 global하게 설치해주어야 한다는 점에서 컴퓨터에 설치되어 있지 않은 파이썬 버전으로 가상환경을 만들어야하는 경우, 필요한 python 버전을 python 공홈에서 매번 설치하고, 환경변수를 변경해줘야해서 매우 귀찮다.

< venv 사용법 >

1. 필요한 python 버전이 윈도우에 설치된 파이썬 버전과 다를 경우,

    파이썬 공홈으로부터 필요한 파이썬 버전을 설치한다. 

# 현재 설치된 모든 파이썬의 버전을 확인하는 명령어
py -0

"""
 -V:3.12 *        Python 3.12 (64-bit)
 -V:3.11          Python 3.11
"""

 

2. 환경변수 수정 or 추가

"python" 명령어를 cli 환경에서 사용하기 위해서는 환경 변수를 추가해야한다.

기존에 3.11가 설치되어있었다. python 3.11 의 python.exe와 pip.exe가 아래 위치에 설치되어 있었고, 환경변수에도 아마 아래의 위치가 추가되어 있었을 것이다.

• C:\Program Files\WindowsApps\PythonSoftwareFoundation.Python.3.11_3.11.2544.0_x64__qbz5n2kfra8p0\
  의 기존 환경 변수를 C:\Python312\python.exe와 C:\Python312\Scripts\pip.exe가 있는 디렉토리 위치로 아래 사진처럼 변경해주어야 한다. ( 두 개 이상의 python 실행 파일 위치를 환경 변수에 추가하면 충돌이 나서 에러가 발생할 수 있기 때문에 기존 환경변수를 제거하고 추가해줘야 한다.)

 

• 시스템 속성 - 환경 변수 - 환경 변수 편집 - 편집 or 새로 만들기 - 아래 경로를 추가해준다.
  • C:\Python312\Scripts\
  • C:\Python312\

 

3. venv 모듈로 가상환경 생성

# python -m venv <가상환경 이름>
python -m venv .venv

# 가상환경 실행
.venv\Scripts\activate

# 가상환경 종료
deactivate

 

 

 

* pyenv ( 파이썬 버전 관리 X, 가상환경 관리 O )

python 버전관리를 위한 오픈소스 라이브러리다. 파이썬 버전만 관리해주고, 가상환경을 생성할 수는 없기 때문에, 가상환경을 관리하는 툴인 pyenv-virtualenv을 보통 같이 설치해서 사용한다.

• 장점:
  기존에 공홈에서 다운 받는 절차와 환경변수를 변경해주는 수동 설치 방법이 아니라 명령어로 손쉽게 python 버전을 설치 및 삭제할 수 있어서 관리가 편하다.
• 단점:
  1.pyenv는 python 버전만 관리해주기 때문에 가상환경을 위한 라이브러리인 virtualenv를 따로 설치해줘야한다.
    (참고로 pyenv와 virtualenv를 한 번에 사용 가능한 pyenv-virtualenv 라이브러리도 있다. 윈도우 지원 x)
  2. pyenv 공식 깃헙에서 윈도우를 지원하지 않는다. 하지만 kirankotari라는 훌륭한 분이 fork를 떠서 pyenv-win 라는 깃헙에서 윈도우용 pyenv를 만들었다. 마찬가지로 가상환경관리를 위해선 pyenv-win-venv을 설치해야한다.

< pyenv-win 사용법 >

1. pyenv-win 깃허브에 설명된 설치 과정에 따라 설치한다.

• 나에 경우 powershell7을 사용하고 있는데, Quick start의 설명에 대로 설치가 안 되어서, git clon 방식으로 설치하였다. 간단히 정리하면 아래와 같다. 

# %USERPROFILE%\.pyenv 위치에 소스 코드 다운로드.
git clone https://github.com/pyenv-win/pyenv-win.git "%USERPROFILE%\.pyenv"

 

# PYENV, PYENV_ROOT, PYENV_HOME 환경변수를 추가하는 명령어를 차례대로 복붙해서 실행해준다.
[System.Environment]::SetEnvironmentVariable('PYENV',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")

[System.Environment]::SetEnvironmentVariable('PYENV_ROOT',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")

[System.Environment]::SetEnvironmentVariable('PYENV_HOME',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")

[System.Environment]::SetEnvironmentVariable('path', $env:USERPROFILE + "\.pyenv\pyenv-win\bin;" + $env:USERPROFILE + "\.pyenv\pyenv-win\shims;" + [System.Environment]::GetEnvironmentVariable('path', "User"),"User")

 

• 시스템 변수가 아닌 사용자 변수를 보면 아래와 같이 pyenv가 추가된 것을 볼 수 있다.
  (pyenv-win-venv는 아래 pyenv-win-venv 설치 후에 추가된 것.)

 

• pyenv --version 명령어를 입력시 버전이 출력되면 잘 설치된 것이다.
  (참고: powershell을 껐다 켜야 환경변수가 적용된다.)

pyenv --version # pyenv 3.1.1

 

• pyenv 명령어 정리

# 설치가능한 파이썬 버전 목록을 볼 수 있다.
pyenv install -l 

# 특정 파이썬 버전을 설치하는 명령어.
pyenv install 3.12.8

# 현재 어떤 버전의 파이썬을 사용하고 있는지와 파이썬 실행파일의 위치를 출력.
pyenv version

# 설치한 파이썬 버전의 목록과 파일 위치를 출력.
pyenv versions

# 파이썬 버전을 global or local로 사용하고자 할 때.
pyenv local 3.12.8
pyenv global 3.12.8

 

2. pyenv-win-venv 깃허브의 설명을 참고하여 설치

먼저 pyenv-win 설치가 선행되어야 한다.

# "$HOME\.pyenv-win-venv" 위치에 깃 클론
git clone https://github.com/pyenv-win/pyenv-win-venv "$HOME\.pyenv-win-venv"

 

# 환경 변수 추가 명령어
[System.Environment]::SetEnvironmentVariable('path', $env:USERPROFILE + "\.pyenv-win-venv\bin;"  + [System.Environment]::GetEnvironmentVariable('path', "User"),"User")

 

• pyenv-win-venv 또는 pyenv-venv 명령어를 입력하여 잘 설치되었는지 확인.

pyenv-win-venv # pyenv-venv 명령어와 같다. 혼용해서 사용해도 됨.
"""
pyenv-win-venv v0.6.5
Copyright (c) Arbaaz Laskar <arzkar.dev@gmail.com>

Usage: pyenv-win-venv <command> <args>

A CLI to manage virtual envs with pyenv-win

Commands:
init                search for .python-version file in the
                    current directory and activate the env
activate            activate an env
deactivate          deactivate an env
completion          autocomplete script for powershell
install             install an env
uninstall           uninstall an env
uninstall self      uninstall the CLI and its envs
list <command>      list all installed envs/python versions
local               set the given env in .python-version file
config              show the app directory
update self         update the CLI to the latest version
which <command>     show the full path to an executable
help <command>      show the CLI/<command> menu

Flags:
debug               To show debug log
"""

 

 

* pyenv-venv activate, 가상환경 활성화시 powershell이 아닌 cmd 환경으로 바뀌는 버그 수정(아래 접은 글 확인)

 

깃클론으로 설치해서 그런건지? powershell에서 pyenv-venv activate을 실행하면 가상환경이 cmd환경에서 켜졌다.

찾다보니, C:\Users\유저이름\.pyenv-win-venv\bin\ pyenv-win-venv.ps1 파일의 소스를 일부 바꿔주니 해결됐다.

# Auto-detect the shell

if ($MyInvocation.MyCommand.CommandType -eq "ExternalScript") {

    $invokedShell = "bat"

}

else {

    $invokedShell = "ps1"

}

위의 코드를 모두 지우고 아래와 같이 바꾸니 powershell7으로 잘 켜졌다. 

분석: 

$MyInvocation.MyCommand.CommandType 는 powershell에서 커맨드가 어떤 쉘에서 입력되었는지(현재 사용중인 쉘인지 외부 쉘인지)를 출력해주는 명령어라고한다. ExternalScript(외부쉘)이면 CMD가 켜지고, 그 외에 경우 파워쉘이 켜지라고 되어있는 것이다. 그래서 위의 if문을 싹 다 지우고 항상 파워셀로 켜지도록 아래 한 줄로 대체했다.

$invokedShell = "ps1"

 

3. pyenv-venv 명령어 정리

# 가상환경 생성: pyenv-venv install <파이썬버전> <가상환경 이름>
pyenv-venv install 3.12.9 3.12.9 # 일부러 가상환경이름을 파이썬 버전 이름과 일치시켰다.

# 가상환경 활성화: pyenv-venv activate <가상환경 이름>
pyenv-venv activate 3.12.9 

# 가상환경 종료
pyenv-venv deactivate
exit

 

4. pyenv-win-venv로 만든 가상환경을 poetry에 연결하려고 했으나 엑세스거부 발생 -> 최근이슈, 과거이슈

poetry 2.0.1에서 window 파일에 엑세스 거부 문제가 있는 것 같다. 최근에 이슈 올린 사람도 있다.

 

 

* poetry ( 파이썬 버전 관리 X, 가상환경 관리 O, 패키지 관리 O )

poetry는 로컬pc의 global python.exe외의 poetry 전용 python.exe 파일이 따로 있고, 가상환경을 만들 수 있다(poetry 자체도 python -m venv venv로 만든 가상환경이라고 생각하면 편하다.)

 

장점: pyenv로 파이썬 버전을 변경한 후에 poetry로 가상환경을 만들면  패키지 관리도 가능하므로 편하다.

 

< poetry 설치 및 사용법 >

1. 공홈을 참고해서 설치하자.

아래 둘 중 하나 아무난 걸로 설치해도 사실 상관없다. 어차피 poetry env use <python.exe경로>를 이용하면 해당 경로의 파이썬 버전으로 가상환경을 만들 수 있다. 다만 Base 파이썬 버전이 무엇이냐가 다를 뿐이다. 예를들어 poetry install으로 가상환경을 생성하면서 의존성을 설치할 때 Base의 파이썬 버전을 기준으로 가상환경 버전을 자동 생성한다.

# 현재 사용중인 파이썬 버전으로 poetry를 사용하고 싶으면 명령어 끝에 python을 넣는다.
# pyenv로 관리되는 파이썬 버전을 설치할 것이므로 이걸로 설치.
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

# 로컬 pc에 설치된 파이썬 버전(py -0 명령어로 확인할 수 있는 파이썬 버전)으로 설치하려면 아래 명령어로 설치.
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

 

• 설치 확인

poetry --version # Poetry (version 2.0.1)

 

2. poetry shell  plugin 설치

poetry shell을 현재 프로젝트의 가상환경을 활성화하는 기능이다.

과거 poetry shell이라는 기본 기능이 plugin으로 빠졌다. 

poetry self add poetry-plugin-shell

 

3. poetry 명령어 정리

# 새로운 프로젝트 생성(pyproject.toml을 생성)
poetry new 

# 패키지 추가(pip install과 비슷)
poetry add 

# 패키지 의존성 설치 (기존 lock파일을 기준으로 설치하거나 pyproject.toml의 패키지들을 설치한다.)
# .venv 가상환경을 자동 생성한다.
poetry install

# 가상환경 목록 출력
poetry env list

# 가상환경 파이썬 버전 변경 후 가상환경 생성(단, 현재 폴더에 가상환경이 없어야 함)
# poetry는 conda의 가상환경과 연동이 가능하다
poetry env use <가상환경의 python.exe 주소>

# 가상환경 실행 파일 위치를 출력(가상환경 활성화 아님!)
poetry env activate

# 가상환경 삭제: 현재 엑세스 거부 에러 발생. 하단 이슈 참고
# poetry 2.0.1 버전, 윈도우 11, 2025.01.31 기준.
poetry env remove

# 가상환경 전체 삭제
poetry env remove --all

 

 

복잡하다. 여러가지 라이브러리를 사용해서 관리하는 게 정말 복잡하다.

최근에는 [ 파이썬 버전 관리 + 패키지 관리 + 의존성관리 + 가상환경 + 포매터/린터 서드파티 도구]를 모두 합치고 속도마저 어마무시하게 빠른 "uv"가 있다. Rust로 작성되어서 속도가 빠르다고 한다. 이제 uv가 지배하는 세상이 올 것 같다...

 

다음 포스팅에는 uv 사용법을 정리하는걸로,,

 

참고자료:

https://homubee.tistory.com/38

pyenv+poetry

uv