가상 환경¶

Python 프로젝트를 작업할 때는가상 환경(또는 이와 유사한 메커니즘)을 사용해 각 프로젝트마다 설치하는 패키지를 분리하는 것이 좋습니다.

프로젝트 생성¶

먼저, 프로젝트를 위한 디렉터리를 하나 생성합니다.

제가 보통 하는 방법은 사용자 홈/유저 디렉터리 안에code라는 디렉터리를 만드는 것입니다.

그리고 그 안에 프로젝트마다 디렉터리를 하나씩 만듭니다.

// 홈 디렉터리로 이동$cd// 모든 코드 프로젝트를 위한 디렉터리 생성$mkdircode// 그 code 디렉터리로 이동$cdcode// 이 프로젝트를 위한 디렉터리 생성$mkdirawesome-project// 그 프로젝트 디렉터리로 이동$cdawesome-project

가상 환경 생성¶

Python 프로젝트를처음 시작할 때, 가상 환경을프로젝트 내부에 생성하세요.

$python-mvenv.venv

$uvvenv

해당 명령어는.venv라는 디렉터리에 새로운 가상 환경을 생성합니다.

가상 환경 활성화¶

이후 실행하는 Python 명령어와 설치하는 패키지가 새 가상 환경을 사용하도록, 새 가상 환경을 활성화하세요.

$source.venv/bin/activate

$.venv\Scripts\Activate.ps1

$source.venv/Scripts/activate

가상 환경 활성화 여부 확인¶

가상 환경이 활성화되어 있는지(이전 명령어가 작동했는지) 확인합니다.

$whichpython/home/user/code/awesome-project/.venv/bin/python

$Get-CommandpythonC:\Users\user\code\awesome-project\.venv\Scripts\python

pip 업그레이드¶

pip로 패키지를 설치한다면(Python에 기본으로 포함되어 있습니다) 최신 버전으로업그레이드하는 것이 좋습니다.

패키지 설치 중 발생하는 다양한 특이한 오류는 먼저pip를 업그레이드하는 것만으로 해결되는 경우가 많습니다.

가상 환경이 활성화된 상태인지 확인한 다음(위의 명령어 사용) 아래를 실행하세요:

$python-mpipinstall--upgradepip---> 100%

$python-mensurepip--upgrade---> 100%

.gitignore 추가하기¶

Git을 사용하고 있다면(사용하는 것이 좋습니다),.venv의 모든 내용을 Git에서 제외하도록.gitignore 파일을 추가하세요.

$echo"*">.venv/.gitignore

*

패키지 설치¶

환경을 활성화한 뒤, 그 안에 패키지를 설치할 수 있습니다.

패키지 직접 설치¶

급하게 작업 중이고 프로젝트의 패키지 요구사항을 선언하는 파일을 사용하고 싶지 않다면, 패키지를 직접 설치할 수 있습니다.

$pipinstall"fastapi[standard]"---> 100%

$uvpipinstall"fastapi[standard]"---> 100%

requirements.txt에서 설치¶

requirements.txt가 있다면, 이제 이를 사용해 그 안의 패키지를 설치할 수 있습니다.

$pipinstall-rrequirements.txt---> 100%

$uvpipinstall-rrequirements.txt---> 100%

fastapi[standard]==0.113.0pydantic==2.8.0

프로그램 실행¶

가상 환경을 활성화한 뒤에는 프로그램을 실행할 수 있으며, 설치한 패키지가 들어있는 가상 환경 내부의 Python을 사용하게 됩니다.

$pythonmain.pyHello World

에디터 설정¶

아마 에디터를 사용할 텐데, 자동 완성과 인라인 오류 표시를 받을 수 있도록 생성한 가상 환경을 사용하도록 설정하세요(대부분 자동 감지합니다).

예를 들면:

• VS Code
• PyCharm

가상 환경 비활성화¶

프로젝트 작업을 마쳤다면 가상 환경을비활성화할 수 있습니다.

$deactivate

이렇게 하면python을 실행할 때, 해당 가상 환경과 그 안에 설치된 패키지에서 실행하려고 하지 않습니다.

작업할 준비 완료¶

이제 프로젝트 작업을 시작할 준비가 되었습니다.

가상 환경을 왜 사용하나요¶

FastAPI로 작업하려면Python을 설치해야 합니다.

그 다음 FastAPI와 사용하려는 다른패키지를설치해야 합니다.

패키지를 설치할 때는 보통 Python에 포함된pip 명령어(또는 유사한 대안)를 사용합니다.

하지만pip를 그대로 직접 사용하면, 패키지는전역 Python 환경(전역 Python 설치)에 설치됩니다.

문제점¶

그렇다면, 전역 Python 환경에 패키지를 설치하면 어떤 문제가 있을까요?

어느 시점이 되면서로 다른 패키지에 의존하는 다양한 프로그램을 작성하게 될 것입니다. 그리고 작업하는 프로젝트 중 일부는 같은 패키지의서로 다른 버전에 의존할 수도 있습니다. 😱

예를 들어philosophers-stone이라는 프로젝트를 만들 수 있습니다. 이 프로그램은harry라는 다른 패키지의 버전1에 의존합니다. 그래서harry를 설치해야 합니다.

flowchart LR    stone(philosophers-stone) -->|requires| harry-1[harry v1]

그다음, 나중에prisoner-of-azkaban이라는 또 다른 프로젝트를 만들고, 이 프로젝트도harry에 의존하지만, 이 프로젝트는harry 버전3이 필요합니다.

flowchart LR    azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3]

하지만 이제 문제가 생깁니다. 로컬가상 환경이 아니라 전역(전역 환경)에 패키지를 설치한다면, 어떤 버전의harry를 설치할지 선택해야 합니다.

philosophers-stone을 실행하고 싶다면, 먼저harry 버전1을 다음과 같이 설치해야 합니다:

$pipinstall"harry==1"

그리고 전역 Python 환경에harry 버전1이 설치된 상태가 됩니다.

flowchart LR    subgraph global[global env]        harry-1[harry v1]    end    subgraph stone-project[philosophers-stone project]        stone(philosophers-stone) -->|requires| harry-1    end

하지만prisoner-of-azkaban을 실행하려면harry 버전1을 제거하고harry 버전3을 설치해야 합니다(또는 버전3을 설치하기만 해도 버전1이 자동으로 제거됩니다).

$pipinstall"harry==3"

그러면 전역 Python 환경에harry 버전3이 설치된 상태가 됩니다.

그리고philosophers-stone을 다시 실행하려고 하면,harry 버전1이 필요하기 때문에작동하지 않을 가능성이 있습니다.

flowchart LR    subgraph global[global env]        harry-1[<strike>harry v1</strike>]        style harry-1 fill:#ccc,stroke-dasharray: 5 5        harry-3[harry v3]    end    subgraph stone-project[philosophers-stone project]        stone(philosophers-stone) -.-x|⛔️| harry-1    end    subgraph azkaban-project[prisoner-of-azkaban project]        azkaban(prisoner-of-azkaban) --> |requires| harry-3    end

이제 이런 일이 여러분의모든 프로젝트가 의존하는많은 다른패키지에서도 일어난다고 상상해 보세요. 이는 관리하기가 매우 어렵습니다. 그리고 결국 일부 프로젝트는 패키지의호환되지 않는 버전으로 실행하게 될 가능성이 높으며, 왜 무언가가 작동하지 않는지 알지 못하게 될 수 있습니다.

또한 운영체제(Linux, Windows, macOS 등)에 따라 Python이 이미 설치되어 있을 수도 있습니다. 그런 경우에는 시스템에필요한 특정 버전의 패키지가 일부 미리 설치되어 있을 가능성이 큽니다. 전역 Python 환경에 패키지를 설치하면, 운영체제에 포함된 프로그램 일부가깨질 수 있습니다.

패키지는 어디에 설치되나요¶

Python을 설치하면 컴퓨터에 몇몇 파일이 들어 있는 디렉터리가 생성됩니다.

이 디렉터리 중 일부는 설치한 모든 패키지를 담는 역할을 합니다.

다음을 실행하면:

// 지금은 실행하지 마세요, 예시일 뿐입니다 🤓$pipinstall"fastapi[standard]"---> 100%

FastAPI 코드를 담은 압축 파일을 다운로드합니다. 보통PyPI에서 받습니다.

또한 FastAPI가 의존하는 다른 패키지들의 파일도다운로드합니다.

그 다음 모든 파일을압축 해제하고 컴퓨터의 한 디렉터리에 넣습니다.

기본적으로, 다운로드하고 압축 해제한 파일들은 Python 설치와 함께 제공되는 디렉터리, 즉전역 환경에 저장됩니다.

가상 환경이란 무엇인가요¶

전역 환경에 모든 패키지를 두는 문제에 대한 해결책은 작업하는각 프로젝트마다 가상 환경을 사용하는 것입니다.

가상 환경은 전역 환경과 매우 유사한 하나의디렉터리이며, 프로젝트의 패키지를 설치할 수 있습니다.

이렇게 하면 각 프로젝트는 자체 가상 환경(.venv 디렉터리)과 자체 패키지를 갖게 됩니다.

flowchart TB    subgraph stone-project[philosophers-stone project]        stone(philosophers-stone) --->|requires| harry-1        subgraph venv1[.venv]            harry-1[harry v1]        end    end    subgraph azkaban-project[prisoner-of-azkaban project]        azkaban(prisoner-of-azkaban) --->|requires| harry-3        subgraph venv2[.venv]            harry-3[harry v3]        end    end    stone-project ~~~ azkaban-project

가상 환경을 활성화한다는 것은 무엇을 의미하나요¶

가상 환경을 활성화한다는 것은, 예를 들어 다음과 같은 명령어로:

$source.venv/bin/activate

$.venv\Scripts\Activate.ps1

$source.venv/Scripts/activate

다음 명령어들에서 사용할 수 있는 몇몇환경 변수를 생성하거나 수정하는 것을 의미합니다.

그 변수 중 하나가PATH 변수입니다.

가상 환경을 활성화하면 가상 환경의 경로인.venv/bin(Linux와 macOS) 또는.venv\Scripts(Windows)를PATH 환경 변수에 추가합니다.

가령 환경을 활성화하기 전에는PATH 변수가 다음과 같았다고 해보겠습니다:

/usr/bin:/bin:/usr/sbin:/sbin

C:\Windows\System32

가상 환경을 활성화한 뒤에는PATH 변수가 다음과 같이 보일 수 있습니다:

/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin

/home/user/code/awesome-project/.venv/bin

/home/user/code/awesome-project/.venv/bin/python

C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32

C:\Users\user\code\awesome-project\.venv\Scripts

C:\Users\user\code\awesome-project\.venv\Scripts\python

중요한 세부 사항은 가상 환경 경로가PATH 변수의맨 앞에 들어간다는 점입니다. 시스템은 다른 어떤 Python보다도먼저 이를 찾게 됩니다. 이렇게 하면python을 실행할 때, 다른 어떤python(예: 전역 환경의python)이 아니라가상 환경의 Python을 사용하게 됩니다.

가상 환경을 활성화하면 다른 몇 가지도 변경되지만, 이것이 그중 가장 중요한 것 중 하나입니다.

가상 환경 확인하기¶

가상 환경이 활성화되어 있는지 확인할 때는, 예를 들어 다음을 사용합니다:

$whichpython/home/user/code/awesome-project/.venv/bin/python

$Get-CommandpythonC:\Users\user\code\awesome-project\.venv\Scripts\python

이는 사용될python 프로그램이가상 환경 내부에 있는 것이라는 뜻입니다.

Linux와 macOS에서는which, Windows PowerShell에서는Get-Command를 사용합니다.

이 명령어는PATH 환경 변수에 있는 경로를순서대로 확인하면서python이라는 프로그램을 찾습니다. 찾는 즉시, 그 프로그램의경로를 보여줍니다.

가장 중요한 부분은python을 호출했을 때, 실행될 정확한 "python"이 무엇인지 알 수 있다는 점입니다.

따라서 올바른 가상 환경에 있는지 확인할 수 있습니다.

가상 환경을 왜 비활성화하나요¶

예를 들어philosophers-stone 프로젝트에서 작업하면서,그 가상 환경을 활성화하고, 패키지를 설치하고, 그 환경으로 작업하고 있다고 해보겠습니다.

그런데 이제다른 프로젝트인prisoner-of-azkaban에서 작업하고 싶습니다.

해당 프로젝트로 이동합니다:

$cd~/code/prisoner-of-azkaban

philosophers-stone의 가상 환경을 비활성화하지 않으면, 터미널에서python을 실행할 때philosophers-stone의 Python을 사용하려고 할 것입니다.

$cd~/code/prisoner-of-azkaban$pythonmain.py// sirius 임포트 오류, 설치되어 있지 않습니다 😱Traceback (most recent call last):    File "main.py", line 1, in <module>        import sirius

하지만 가상 환경을 비활성화하고prisoner-of-askaban에 대한 새 가상 환경을 활성화하면,python을 실행할 때prisoner-of-azkaban의 가상 환경에 있는 Python을 사용하게 됩니다.

$cd~/code/prisoner-of-azkaban// 비활성화를 위해 이전 디렉터리에 있을 필요는 없습니다. 어디서든, 다른 프로젝트로 이동한 뒤에도 할 수 있습니다 😎$deactivate// prisoner-of-azkaban/.venv의 가상 환경을 활성화하세요 🚀$source.venv/bin/activate// 이제 python을 실행하면, 이 가상 환경에 설치된 sirius 패키지를 찾습니다 ✨$pythonmain.pyI solemnly swear 🐺

대안들¶

이 문서는 시작을 돕고, 내부에서 모든 것이 어떻게 작동하는지 알려주는 간단한 가이드입니다.

가상 환경, 패키지 의존성(requirements), 프로젝트를 관리하는 방법에는 많은대안이 있습니다.

준비가 되었고프로젝트 전체, 패키지 의존성, 가상 환경 등을관리하는 도구를 사용하고 싶다면uv를 사용해 보시길 권합니다.

uv는 많은 일을 할 수 있습니다. 예를 들어:

• 여러 버전을 포함해Python을 설치
• 프로젝트의가상 환경 관리
• 패키지 설치
• 프로젝트의 패키지의존성과 버전 관리
• 의존성을 포함해 설치할 패키지와 버전의정확한 세트를 보장하여, 개발 중인 컴퓨터와 동일하게 프로덕션에서 실행할 수 있도록 합니다. 이를locking이라고 합니다
• 그 외에도 많은 기능이 있습니다

결론¶

여기까지 모두 읽고 이해했다면, 이제 많은 개발자들보다 가상 환경에 대해훨씬 더 많이 알게 된 것입니다. 🤓

이 세부 사항을 알고 있으면, 나중에 복잡해 보이는 무언가를 디버깅할 때 아마도 도움이 될 것입니다.내부에서 어떻게 작동하는지 알고 있기 때문입니다. 😎