Python 개발환경 구축 (VSCode + Anaconda)

1. 이걸 왜 하는가

Python은 numpy, pytorch처럼 남이 만들어 둔 library를 가져다 쓰는 언어다. 그런데 프로젝트를 여러 개 진행하다 보면, 프로젝트마다 필요한 라이브러리 버전이 서로 달라야 하는 일이 생긴다. 예를 들어 A 프로젝트는 numpy 2.x를 사용하고, B 프로젝트는 numpy 1.x를 사용하는 식이다.

이를 위해 Python에는 **가상환경 (virtual environment)**을 설정하고, 각 가상환경마다 별도의 라이브러리를 설치한 후, 코드를 실행할 때 가상환경을 하나 골라서 실행하는 형태를 가진다.

이 가상환경을 관리하는 프로그램이 Anaconda이다. 여기서는 Anaconda를 포함하여 Python 코드를 쓰고 실행하는 편집기(IDE)인 VSCode를 설치해본다.

2. VSCode 설치

2.1 설치 파일 내려받기

Visual Studio Code 배포 사이트에서 Windows 10, 11을 다운로드 받는다.
※ 만약 윈도우가 아닌 Mac을 사용 시, macOS version+를 다운로드 받는다.

다운로드가 완료되면 Installer를 실행한다.

2.2 설치

라이선스 동의와 설치 경로를 선택하는 부분을 지나면, 아래와 같은 추가 작업 선택 화면이 나온다.
이때 그림상의 체크박스 4개를 다 체크한다.
VSCode 설치 중 나타나는 체크박스

만약 체크를 깜빡한 경우, VSCode를 지웠다 설치할 필요 없다. 받아둔 설치 파일을 그대로 다시 실행하면 같은 화면이 다시 나오고, 이번엔 체크한 상태로 [다음(Next)]를 누르면 덮어쓰기로 반영된다.

2.3 설치 확인

파일 탐색기로 아무 폴더를 열고, 우클릭했을 때 아래처럼 메뉴에 [Code(으)로 열기] 또는 [Open with Code]가 보이면 성공이다.
이때, Windows 11의 경우 기본적으로 메뉴를 축약해두는데, 메뉴 맨 아래 [더 많은 옵션 표시]를 누르면 위와 같이 전체 메뉴가 나온다.
정상적으로 설치한 경우

3. VSCode 설정

GitHub 포털에서 Gmail로 계정을 생성한다.

이후, VSCode를 켜고 **왼쪽 아래 사람 모양 아이콘(Accounts)**을 누른 뒤 Sign in to Sync Settings를 선택한다. 브라우저가 열리면서 인증을 요청하고, 승인하면 VSCode로 돌아온다.
로그인 방법

이때 아래와 같이 Copilot을 사용할지에 대한 여부를 물어볼 수 있는데, Allow를 선택한다.
깊게 고민하지 말고 Allow를 누르자

로그인되면, 앞으로 Color Theme 등 변경하는 설정들을 다음과 같이 F1 키를 누른 후 [Settings Sync: Sync Now]를 이용해 상시 동기화할 수 있다.
F1 키를 누르고 "sync"를 타입해보자

4. Anaconda 설치

4.1 설치 파일 내려받기

Anaconda 공식 배포 사이트에서 Gmail로 계정을 생성한 후, Windows용 64-bit 그래픽 인스톨러를 받는다.

4.2 설치

설치 과정은 본인의 계정 이름에 한글, 특수기호, 공백이 포함된 경우와 그렇지 않은 경우로 나뉜다.

4.2.1 계정 이름에 한글, 특수기호, 공백이 포함되지 않은 경우:

받은 Installer를 (.exe 파일) 실행하고 아래와 같이 **"Just Me (recommended)"**를 선택한다.
Anaconda 설치 유형 선택 화면

그리고 기본 설치 경로로 고르자. 기본 설치 경로는 C:\Users\계정명\anaconda3와 같은 형식으로 나타난다면 정상이다.
절대로 Next 버튼을 마구잡이로 누르지 말고 경로만 설정하고 4.3절로 가자.

4.2.2 계정 이름에 한글, 특수기호, 공백이 포함된 경우:

만약 본인의 계정 이름에 한글, 특수기호, 공백이 포함된 경우 설치 경로를 C:\anaconda3로 바꿔야 한다. 만약 아래와 같은 에러가 발생한다면 C:\ 아래에 일반 사용자에게 쓰기 권한이 없는 경우다. 이 경우, 다음과 같이 설치 폴더를 미리 만들어두고 내 계정에 권한을 넘겨주어야 한다:

C:\에 설치 권한이 없는 경우 보게 되는 화면

먼저 켜져 있던 Installer를 종료하고, PowerShell을 관리자 권한으로 실행하자 (Win 키를 누르고 PowerShell을 검색한 뒤 Ctrl + Shift + Enter를 누르면 된다). 그리고 아래 명령어를 입력한다.

$u = whoami
if (-not (Test-Path C:\anaconda3)) { mkdir C:\anaconda3 }
icacls C:\anaconda3 /grant "${u}:(OI)(CI)F" /T

다시 Installer를 실행하고 (관리자 권한 X) 설치 경로를 C:\anaconda3로 설정한다.
절대로 Next 버튼을 마구잡이로 누르지 말고 경로만 설정하고 4.3절로 가자.

4.3 PATH 설정

설치를 진행하다 보면 아래와 같이 체크박스가 나타나는데 위 3개를 체크해준다.

체크를 안 하고 지나가면 골치 아파진다.

만약 실수로 체크를 안 했다면 Anaconda를 clean uninstall 후 재설치할 것을 추천한다.

4.4 설치 완료

Anaconda의 용량은 최대 10 GB 가까이 되며, 컴퓨터 사양에 따라 설치에 최대 1시간 가까이 소요될 수 있다.
설치가 완료되면 Navigator를 실행시킬 거냐와 같은 체크박스가 나타나는데, 다 체크 해제하고 설치를 마무리하면 된다.

5. conda 작동 테스트

5.1 Anaconda 정상 설치 여부 확인

Anaconda 설치가 끝났으면, 이제 PC가 conda를 찾을 수 있는지를 확인할 차례다.

이를 위해 Win + R에서 cmd를 입력해 명령 프롬프트 터미널을 실행시키고, 아래 명령어를 입력한다. 이때 VSCode의 터미널(메뉴 bar의 Terminal >> New Terminal)을 써도 된다.

where conda

만약, macOS나 Linux와 같은 Unix 시스템을 사용한다면 where 대신에 which 명령어를 사용하니 참고하자:

which conda

위와 같이 나타난다면 Anaconda 정상 설치된 것이다.

만약 위와 같이 나타나지 않는다면 아래 5.2를 시도하자.

5.2 (where conda 정상 작동하지 않는 경우) 환경 변수 직접 등록하기

아마 대부분 설치할 때 PATH 체크박스를 빼먹은 경우일 것이다. 이 경우 아래 절차를 따라 하면 conda를 살려낼 수 있다. 그러나, 슬쩍 보면 알겠지만 절차가 복잡한 데다 위험 표시가 곳곳에 도사리고 있는 만큼 각별한 주의가 필요하다. 만약 내가 자신이 없다 싶으면 4.3절로 돌아가서 Anaconda를 재설치하는 편이 낫다.

각오가 섰다면, 단순히 번호 순서대로 따라갈 것이 아니라 내용 전체를 숙지하고 시작하자:

1. Win 키를 누르고 환경 변수를 검색해 시스템 환경 변수 편집을 실행한다.
2. [환경 변수(N)...] 버튼을 누른다.
3. 위쪽 사용자 변수 목록에서 Path를 선택하고 [편집(E)...]을 누른다.
4. [새로 만들기(N)]를 눌러 아래 주소를 한 줄씩 추가한다.

• C:\Users\{USERNAME}\anaconda3
• C:\Users\{USERNAME}\anaconda3\Scripts
• C:\Users\{USERNAME}\anaconda3\Library\bin
• C:\Users\{USERNAME}\anaconda3\Library\usr\bin
• C:\Users\{USERNAME}\anaconda3\Library\mingw-w64\bin

이때 반드시 실제 Anaconda가 설치된 경로로 변경해서 기입하자. 예를 들어, C:\anaconda3에 설치했다면 C:\Users\{USERNAME}이 아닌 C:\anaconda3\...가 된다. 그리고 {USERNAME}와 같은 중괄호 + 대문자 표기법은 환경변수를 나타내니 주의하자. 문자 그대로 {USERNAME}를 입력하면 안 된다.

하라는 대로 하지 않은 자의 죄

5. 설정이 끝나면 반드시 [확인]을 세 번 눌러 창을 모두 닫는다. 그냥 창을 닫으면 변경 내역이 적용되지 않는다.
6. 열려 있던 터미널과 VSCode를 전부 종료한 뒤 새로 연다. 환경 변수는 프로그램이 시작될 때 한 번만 읽는다.
7. where conda를 다시 실행해 정상적으로 conda 경로가 출력되는지 확인한다.

5.3 (Windows OS만 해당) PowerShell 사용 권한 설정

사용하는 OS가 Windows인 경우, PowerShell을 관리자 권한(Ctrl + Shift + Enter)으로 열고 아래 명령어를 실행하자.

Set-ExecutionPolicy Unrestricted

허가 권한에 대해 물어보면 대답은 "[A] 모두 예(A)"를 선택하면 된다.

Set-ExecutionPolicy Unrestricted 실행 결과

5.4 터미널 실행 시 conda 자동 활성화시키기

conda가 확인되면 다음 명령을 실행한다.

conda init --all

이 명령은 cmd, PowerShell, Bash 등 설치된 모든 터미널(셸, Shell)에 conda 초기화 코드를 심어 준다.
커맨드를 실행하면 아래와 같이 출력된다.

conda init --all 실행 결과. 사용자마다 출력 결과는 다를 수 있다.

이제 터미널을 완전히 닫았다가 새로 연다.

사용하는 터미널이 PowerShell이라면, 새로운 터미널을 열었을 때 빨간색 글씨로 UnauthorizedAccess 오류가 뜰 수 있다. 이는 위 5.3절을 skip해서 생긴 문제이니 5.3을 실행하자.

5.5 conda 작동 테스트

새로 연 터미널에서 다음을 실행한다.

conda activate base
python --version
conda --version

작동 테스트 결과

위 그림과 같이 터미널 프롬프트상에서 (base)로 시작하면 정상적으로 설치가 완료된 것이다. 만약 (base) 표시가 안 보인다면 conda activate base로 활성화하자.

6. 가상환경 만들기

신규 가상환경을 생성하는 command는 아래와 같다.

conda create -n {ENV} python=3.14

• -n {ENV}: 환경 이름이다. {ENV} 대신 본인이 사용할 프로젝트 이름을 쓰자 (예: myenv). 이때 한글, 특수기호, 공백은 절대로 never 사용하지 않는다.
• python=3.14: 이 환경에 설치할 Python 버전이다.

중간에 Proceed ([y]/n)? 표시가 나오면 주저하지 말고 y를 입력하자.

conda create로 가상환경을 만드는 과정

생성이 끝나면 가상환경을 활성화한다.

conda activate {ENV}

이때, 터미널상에서 프롬프트가 (base)에서 (myenv)와 같이 생성한 가상환경명으로 바뀌면 성공이다.

만들어진 환경 목록은 다음으로 확인할 수 있다.

conda env list

conda env list 실행 결과

자주 사용되는 환경 관리 명령은 다음과 같다:

7. 필수 패키지 설치

터미널에서 새로 생성한 (myenv) 환경이 활성화된 상태인지 확인하고, 아래와 같이 5개의 Python 라이브러리들을 설치한다. 이때 pip install numpy, pip install scipy처럼 순차적으로 하나씩 실행해도 된다.

pip install numpy scipy pandas matplotlib scikit-learn

설치 결과

지금 설치하는 각 라이브러리의 용도는 아래와 같다.

설치가 끝나면 실제로 불러와지는지도 확인해보자:

python -c "import numpy, scipy, pandas, matplotlib, sklearn; print('all ok')"

conda install -c conda-forge numpy scipy pandas matplotlib scikit-learn

8. VSCode 환경 설정

8.1 확장 프로그램 (Extension) 설치

VSCode는 설치 직후엔 그냥 텍스트 편집기다. Python 코드를 제대로 다루려면 확장 프로그램을 몇 개 설치해야 한다.

왼쪽 사이드바의 블록 모양 아이콘을 누르거나 Ctrl + Shift + X를 눌러 확장 프로그램 탭을 열고, 아래와 같이 Python을 입력한 후 관련 Extension들을 설치한다.

이때 설치해야 하는 Extension들은 아래와 같다:

8.2 작업 폴더(Workspace) 열기

이제 사용하려는 폴더에서 우클릭을 하면 아래와 같이 [VSCode 로 열기] 버튼이 있다.
그냥 VSCode를 열고나서 File > Open Folder를 해도 된다.

VSCode가 켜지면 아래와 같이 default로 restrict 모드가 걸려 있을 것이다. 아래 상태표시줄의 버튼을 누르면

아래와 같은 창이 뜨고 [Trust]를 눌러주자.
널 믿겠다

우리가 한 것은 VSCode의 기능들(Copilot, Claude도 포함)에게 해당 폴더에 파일을 색인하고, 생성/삭제할 권한을 준 것이다.

8.3 VSCode에 이 환경을 인터프리터로 지정하기

VSCode에서 F1 키를 누르고 [Python: Select Interpreter]를 검색해 실행한 뒤, 목록에서 myenv를 고른다. 창 오른쪽 아래 상태 표시줄에 선택한 환경 이름이 뜨면 된다.

만약 목록에 myenv가 보이지 않는 경우, [Enter interpreter path...]를 눌러 직접 해당 가상환경을 등록해준다. 이때 등록해야 할 대상은 ~\PATH_TO_ANACONDA\envs\{ENV}\python.exe이다. ~\PATH_TO_ANACONDA\는 Anaconda가 설치된 위치다.

여기까지 진행하면 개발환경 구축은 끝이다. VSCode의 자동완성, 오류 표시, 디버거가 가상환경에 설치한 패키지를 기준으로 동작한다.

8.4 Debugger 설정

아래 그림과 같이 Python debugger 설정에 들어가서 "justMyCode" 파라미터를 false로 설정해두자.

justMyCode를 false로 설정하자

위 조치를 해두는 이유는 다음과 같다:

• 코드를 실행했을 때 버그가 있는 경우, 에러가 발생하는 부분에서 일시정지되면서 에러를 발생하게 되고, 이를 통해 우리는 어느 line에서 문제가 발생하는지 알 수 있다.
• 그런데 만약 내 코드가 아닌 Python 라이브러리에 문제가 있는 경우, 에러가 print되면서 debugger가 강제종료되기 때문에 문제가 일어난 위치를 파악하기가 어렵다.
• 이를 해결하기 위해 "내 코드(justMyCode)뿐만 아니라 라이브러리에서 문제가 발생한 경우에도 일시정지시켜줘"라고 설정을 해둔 것이다.

8.5 Color Theme 등 설정

앞으로 오래 볼 화면이니 눈에 맞게 꾸며 두자.

색 테마는 F1 키를 누르고 [Preferences: Color Theme]를 검색해서 설정한다. 방향키로 항목을 옮길 때마다 화면에 바로 적용되어 보이니, 마음에 드는 것에서 Enter를 누르면 된다.

그 밖의 설정들은 F1 키를 누르고 [Preferences: Open Settings (UI)]를 열고 검색 기능을 활용하여 설정한다. 아래는 예시다.