2025.03.29 TIL - 윈도우 wsl 설치 및 Ubuntu 설정, 가상환경 설정

기존에 회사에서 쓰던 프로젝트를 받는 도중, 패키지 설치에서 문제가 생겼다.

RuntimeError: uvloop does not support Windows at the moment

 

찾아보니, uvloop라는 패키지는 윈도우에서 지원하지 않아서 생기는 문제라고 한다.

이전까지는 운영체제가 맥이었어서 문제없이 사용되었다... 그렇다고 uvloop 대신 다른 패키지로 코드를 뜯어고칠 수도 없어, 그냥 내 컴퓨터에 우분투를 깔아 거기에서 프로젝트를 진행하기로 했다.

 

이전까지 wsl을 한번도 써본적이 없어서, 몇시간동안 wsl 깔고 우분투 설치하고 그 김에 도커도 시도해보려다가 포기하고(대체 왜).. 아주그냥 대공사를 거쳤다.

 

1. WSL

1. WSL이란?

WSL(Windows Subsystem for Linux)은 Microsoft Windows 운영 체제에서 Linux 환경을 실행할 수 있도록 해준다. WSL을 이용해 리눅스 환경을 실행하면, 윈도우와 파일 시스템은 공유하기 때문에 윈도우에 저장된 파일들을 그대로 사용할 수 있고, 운영체제만 다르게 설정된다. 버전은 WSL1과 WSL2가 있는데,

• WSL1: Windows와 Linux 커널 간의 다리 역할을 하는 하이퍼바이저 기술을 활용. Windows에서 Linux 바이너리를 직접 실행할 수 있도록 하지만, 파일 시스템 성능은 떨어짐.
• WSL2: Linux 커널을 Windows 시스템 상에서 가상 머신 형태로 실행. 이파일 시스템 성능과 호환성을 개선하고, Docker와 같은 컨테이너 기술을 효율적으로 지원. Windows 10 버전 1903 이상, 빌드 18362 이상에서만 사용 가능.

 

2. WSL 설치 방법

윈도우 터미널 설치

마이크로소프트 스토어에 검색하여 설치한다.

 

Linux 커널 업데이트 패키지 다운로드

마찬가지로, 마이크로소프트 스토어에서 설치

(검색해서 설치하려니 뜨질 않아서 링크로 들어가서 설치했다.)

https://www.microsoft.com/store/productId/9P9TQF7MRM4R?ocid=pdpshare

 

설치가 끝나고 파일탐색기에 들어가면, 좌측 하단에 Linux라는게 새로 생긴걸 볼 수 있다.

아마 처음엔 Linux의 하위 폴더는 뜨지 않을 수도 있다. 내 컴퓨터에는 이미 도커와 우분투가 설치되어 있어 그렇게 뜨는거일 뿐이다.

 

아까 설치한 윈도우 터미널을 검색하여 실행 후 다음 두개의 명령어를 입력해서 WSL을 활성화하자.

윈도우에서 리눅스 배포를 설치하기 위해, 'Linux용 윈도우 하위 시스템 옵션 기능 사용', 'Virtual Machine 플랫폼 옵션 기능을 사용'하도록 하는 명령어이다.

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

 

이렇게 WSL2 설정은 이렇게 끝. 이까지 설정이 끝나면, 재부팅을 꼭 해야한다.

 

2. Ubuntu 설치

마이크로소프트 스토어에서 ubuntu 검색 후 다운로드

버전별로 여러개가 있는데, 나는 24.04.1 버전으로 설치했다.

설치 완료까지 시간이 꽤 걸렸던걸로 기억한다.

 

혹은, 터미널창에서 명령어를 입력해서 설치할 수도 있다.

wsl --install -d Ubuntu-22.04

 

사용자 이름과 패스워드는 본인이 기억할 수 있는걸로 입력하자. 이후 관리자 권한으로 설정할 일이 생길 때, 비밀번호가 필요하다.

 

설치가 완료되면, 아까 설치했던 터미널에 다시 접속하여, WSL2를 기본으로 사용하도록 설정한다.

wsl --set-default-version 2

 

그리고 wsl -l -v를 입력해서 Ubuntu가 문제없이 버전2로 설정되었는지 확인한다.

wsl -l -v

 

이제, 터미널창 상단의 화살표를 눌러, Ubuntu를 실행시켜보자.

 

Ubuntu를 실행하면 아래와 같이 뜰 것이다.

 

앞에서도 말했듯, WSL을 사용하면 윈도우와 리눅스의 운영체제는 분리되어있지만 파일 시스템은 공유되어 있어, 우분투에서 윈도우의 파일을 읽을 수 있고 우분투에서 생성하거나 수정한 파일은 윈도우에서도 동일하게 반영된다.

 

그럼, 윈도우에서 바탕화면에 해당하는 디렉토리를 우분투에서 찾아보자.

/mnt/~(윈도우에서의 디렉토리)에 들어가면 윈도우에서 바탕화면의 항목들이 그대로 있는걸 볼수있다.

 

3. Python 가상환경 설정 및 패키지 설치

내가 제일 헷갈렸던 부분....

Pycharm에서의 Interpreter와 Ubuntu에서 생성한 가상환경이 같은 가상환경이어야 패키지가 제대로 설치된다. 그렇지 않으면 엉뚱한 곳에 패키지를 설치하는게 되어버린다.

 

나도 이것저것 건드리면서 알게된거라, 확실하지 않을 수도 있음..

1. Pycharm Interpreter 설정

이미 git clone을 해둔 프로젝트가 있다.

Pycharm에서 프로젝트를 열 때, 윈도우 디렉토리가 아닌 WSL 디렉토리로 프로젝트를 열자.

 

이런 식으로, 우리가 흔히 아는 ~\Desktop\~~가 아닌 \\wsl.localhost\Ubuntu-24.04\mnt 로 시작하는 디렉토리로 들어가, 작업할 프로젝트를 연다.

 

상단 File > Settings > Project > Python interpreter로 들어가기

 

오른쪽의 Add interpreter > On WSL 클릭

 

Location은 디폴트로 home\(username)\.virtualenv\(프로젝트명)으로 설정되어 있다.

Base interpreter은 python3으로 설정 후 Create 클릭.

 

이렇게 하면 Interpreter 설정 끝

 

2. Ubuntu에서 가상환경 활성화

아까 터미널을 통해 접속한 Ubuntu에서, 다음 명령어를 입력해서 가상환경을 활성화하자.

source /home/(사용자 이름)/.virtualenvs/(프로젝트 이름)/bin/activate

 

활성화가 되었다면, 아래 사진과 같이 괄호가 하나 덧붙여질 것이다.

 

비활성화를 하고싶다면, deactivate를 입력하면 된다.

3. Ubuntu 가상환경에 패키지 설치

이제, 터미널창의 ubuntu의 디렉토리를 프로젝트의 디렉토리로 이동한 다음, 패키지를 설치하자.

나는 프로젝트 내에 requirements.txt가 만들어져 있어 다음 명령어로 간단히 설치했다.

pip install -r requirements.txt

 

설치가 완료되면, 프로젝트를 실행시켜보자.

Ubuntu에서, 다음 명령어를 입력하자. 프로젝트 파일과 디렉토리에 맞춰 명령어를 입력하면 된다.

uvicorn app.api.main:app --reload

 

무사히 서버가 열린걸 확인할 수 있다.