HOLOLOG
GitHub

윈도우에서 WSL+Ubuntu로 Python 개발환경 구축 해봄: Poetry, Windsurf, Jupyter 완벽 가이드

hojun lee · 05/23/2025
커버이미지

MACBOOK에서는 python 환경을 만들기 비교적 쉽다.

windows 환경은 path 때문에 개발환경 셋팅하기가 참 까다롭다. 그래서 셋팅비를 받고 개발 환경을 세팅한 후기를 남기려고 한다. (nice)

  1. WSL을 깔고 ubuntu를 사용한다. ( lunux 환경 )
  2. python3 3.12를 설치한다.
  3. python poetry를 설치한다.
  4. 프로젝트를 리눅스 홈 디렉토리에서 생성 poetry new
  5. windsurf 설치
  6. Windsurf WSL 기능 사용
  7. ipykernel 설치 과 poetry install
  8. jupyter 커널 등록
  9. poetry 커널 실행

window 환경에서 python 설치하여 실행하기 시작

1. WSL을 설치하고 Ubuntu로 리눅스 환경을 쓴다.

Windows 검색에서 "PowerShell"을 관리자 권한으로 실행한다.

아래 명령어를 입력해서 WSL과 Ubuntu를 설치한다.

powershell
wsl --install

설치가 끝나면 컴퓨터를 재부팅한다.

Ubuntu를 처음 실행하면 사용자 이름과 비밀번호를 설정한다.

꽤 오래걸림. 기다림의 미학

2. python3 설치한다.

Ubuntu 터미널에서 아래 명령어로 패키지 목록을 최신으로 만든다.

bash
sudo apt update
python3과 pip를 설치한다.

bash
sudo apt install python3 python3-pip

python3.12가 제대로 설치됐는지 확인한다.

bash
python3 --version

3. python poetry를 설치한다.

poetry 가 뭔대 설치함.

Poetry를 사용하는 주요 이유 중 하나는 파이썬 프로젝트의 의존성을 보다 효율적으로 관리하고, 패키지를 빌드 및 배포하는 데 필요한 도구를 제공한다는 점입니다. 특히, 다양한 버전의 의존성을 관리하고, 패키지 충돌을 방지하며, 일관된 개발 환경을 유지하는 데 도움이 됩니다.

의존성 관리: Poetry는 pyproject.toml 파일을 사용하여 프로젝트의 의존성을 선언하고, 자동으로 의존성을 설치, 업데이트, 제거해 줍니다.

패키지 빌드 및 배포: 프로젝트를 패키징하고, PyPI와 같은 패키지 저장소에 배포하는 데 필요한 기능을 제공합니다.

가상 환경: 각 프로젝트에 대한 격리된 가상 환경을 생성하여 의존성 충돌을 방지합니다.

일관성: poetry.lock 파일을 통해 팀원 모두가 동일한 버전의 의존성을 사용하도록 보장합니다.

간단한 사용: 명령줄 인터페이스를 통해 의존성을 쉽게 관리하고, 패키지를 빌드 및 배포할 수 있습니다.

아하 그럼 설치해보자

공식 설치 스크립트로 poetry를 설치한다.

bash
curl -sSL https://install.python-poetry.org | python3.12 -

poetry 명령어가 안 먹히면, PATH를 추가한다.

bash
export PATH="$HOME/.local/bin:$PATH"

poetry 버전을 확인해서 잘 설치됐는지 본다.

bash
poetry --version

4. 리눅스 홈 디렉토리에서 poetry new로 프로젝트를 만든다.

리눅스 홈 디렉토리에서 프로젝트를 만드는 이유

윈도우 드라이브(/mnt/c/...)에서 poetry install을 하면 권한 에러가 잘 난다. poetry, pip, 가상환경 등 파이썬 도구들은 리눅스 홈디렉토리에서 실행해야 권한 문제 없이 잘 동작한다. PATH 문제로 poetry가 윈도우 쪽에 설치돼 있으면, WSL에서 리눅스용 poetry를 다시 설치하고, PATH를 제대로 잡아줘야 한다. 이런 권한 문제는 단순히 sudo로 해결할 수 있는 게 아니고, 파일시스템 구조와 권한 체계의 차이에서 비롯된 거라 폴더 위치를 옮기는 게 정답이었다.

이런 맥락에서, 나도 poetry install 에러를 겪었고, 리눅스 홈디렉토리에서 작업하는 게 WSL/리눅스 환경에서 가장 안전하다는 걸 직접 체감했다.

홈 디렉토리로 이동한다.

bash
cd ~

새 프로젝트를 만든다. (예시: myproject)

bash
poetry new myproject
cd myproject

프로젝트 폴더 안에 들어가서 작업을 시작한다.

5. windsurf를 설치한다.

vscode 코파일럿과 cursor 중에 windsurf를 사용하려 한다. ( 15불 이라 상대적으로 저렴함)

windsurf 공식 홈페이지에서 설치 파일을 받아서 설치한다.

설치가 끝나면 windsurf를 실행한다.

6. windsurf의 WSL 기능을 쓴다.

Windsurf Remote-WSL 기능의 장점

  • 진짜 리눅스 환경에서 개발 Windsurf Remote-WSL 기능을 쓰면, Windows가 아니라 WSL(리눅스) 내부에서 바로 코딩, 실행, 디버깅이 가능해서 실제 서버나 배포 환경과 거의 똑같은 개발 환경을 쓸 수 있다.
  • 윈도우-리눅스 파일 시스템 문제 해소 윈도우 드라이브(/mnt/c/...)에서 작업하면 권한 문제나 성능 저하가 자주 생기는데, Remote-WSL로 접속하면 리눅스 홈디렉토리에서 바로 작업하니까 이런 문제가 없다.
  • AI/코드 인덱싱, 워크플로우 등 Windsurf 고유 기능 활용 Windsurf는 코드 인덱싱, AI 코드 추천, 워크플로우 자동화, 파일 버전 타임라인 등 기존 IDE에서 못 보던 기능들을 WSL 환경에서도 그대로 쓸 수 있다.
  • 여러 원격 환경 지원 SSH, Dev Container, WSL 등 다양한 원격 환경을 한 IDE에서 통합 관리할 수 있다.
  • 설정이 간단 Windsurf 좌측 하단 "Open a Remote Window" → "Remote-WSL"만 누르면 바로 리눅스 환경에 접속할 수 있다

vscode 였다면?

  • Remote - WSL 확장 설치 VSCode 마켓플레이스에서 "Remote - WSL" 확장을 설치해야 한다.
  • WSL 환경에서 VSCode 실행 WSL 터미널에서 프로젝트 폴더로 이동한 뒤 
bash
code .

이렇게 입력하면, 해당 폴더가 WSL 환경에서 VSCode로 열린다.

  • 좌측 하단 녹색 >< 아이콘(원격 상태 표시기) 클릭 "WSL에 연결"을 선택해서 리눅스 환경에 접속하고, "폴더 열기"로 원하는 리눅스 경로(예: /home/사용자명/프로젝트)를 선택한다.
  • 확장, 터미널, 디버깅 등도 전부 리눅스 환경에서 동작 VSCode에서 설치한 확장, 터미널, 디버깅, 자동완성 등이 모두 리눅스 환경에서 실행된다. 윈도우에서 리눅스 파일을 그냥 열어서 작업하면 이런 기능들이 제대로 동작하지 않는다.
  • 윈도우 드라이브가 아니라 리눅스 홈디렉토리에서 작업 성능과 권한 문제 없이 개발하려면, 프로젝트를 반드시 리눅스 홈디렉토리(예: /home/사용자명/프로젝트)에 두고 작업해야 한다.

실행 방법

windsurf를 켜고, 좌측 하단의 "Open a Remote Window" 또는 "Remote-WSL" 메뉴를 클릭한다.

Ubuntu를 선택하고, 홈 디렉토리의 myproject 폴더를 연다.

windsurf에서 바로 리눅스 환경의 파일을 편집할 수 있다. 이것이 굉장히 꿀이다.

7. poetry에서 ipykernel 설치하고 poetry install 한다.

프로젝트 폴더에서 ipykernel과 jupyter를 설치한다.

bash
poetry add ipykernel jupyter

poetry install로 의존성을 설치한다.

bash
poetry install

8. jupyter 커널을 등록한다.

아래 명령어로 현재 poetry 가상환경을 Jupyter 커널로 등록한다.

bash
poetry run python -m ipykernel install --user --name myproject-kernel --display-name "Python (myproject)"

커널 이름과 표시 이름은 원하는 대로 바꿔도 된다.

9. poetry 커널을 실행한다.

poetry 환경에서 jupyter notebook을 실행한다.

bash
poetry run jupyter notebook

브라우저가 열리면, 새 노트북을 만들고 커널에서 "Python (myproject)"를 선택한다.

이제 poetry 가상환경이 적용된 Jupyter 노트북에서 자유롭게 코딩하면 된다.

test code

import sys
import os

print("Python executable:", sys.executable)
print("Python version:", sys.version)
print("Current working directory:", os.getcwd())

try:
    import ipykernel
    print("ipykernel version:", ipykernel.__version__)
except ImportError:
    print("ipykernel is not installed!")

print("Hello, World!")

이렇게 하면 Windows에서 WSL+Ubuntu+Poetry+Windsurf+Jupyter까지 한 번에 개발 환경을 완성할 수 있다!