uv 설치하고 프로젝트 생성하기

최근에 uv를 다룰 일이 있었는데, 사용했던 명령어들과 발생했던 문제 및 해결 방법 위주로 적어본다.

 

UV란 무엇인가?

uv는 파이썬 패키지 및 프로젝트 관리 도구로, Rust로 만들어져서 pip 등 다른 도구들에 비해 빠르다고 한다.

 

UV 명령어 - 설치, 가상환경, 의존성 관련

• [참고] uv 설치 및 사용법 : https://tilnote.io/pages/67f2927b2a14e2a1ab482f5a
• pip 이용해서 uv 설치 : pip install uv
• uv 버전 확인 (설치 여부 확인을 위해) : uv --version
• 프로젝트 생성 : uv init {프로젝트 이름}
• 설치된 Python 버전 확인 (방법 1) : py -0
• 설치된 Python 버전 확인 (방법 2) : uv python list
• [참고] 특정 Python 버전 설치하기 : uv python install 3.11
• 가상환경 생성 : uv venv
• 가상환경 활성화 (OS 및 Terminal에 따라 명령어 다름)
  • Windows - Git Bash : source .venv/Scripts/activate
  • Windows - Powershell : .\\.venv\\Scripts\\Activate.ps1
• [참고] 가상환경 비활성화 : deactivate
• 의존성 추가 : uv add {라이브러리 이름}

 

Trouble Shooting : Python uv 패키지 설치 중 오류 발생 이슈

상황

Python pip를 통해 Python uv를 설치하고 새로운 uv 프로젝트를 생성한 후 venv 가상환경을 구성한 상황이었다.

해당 가상환경 내에서 Python uv를 통해 streamlit과 ollama 의존성을 추가한 후, ollama 프로그램도 설치해야 한다고 해서 ollama 프로그램을 설치했다.

• 폴더에서 터미널(Git Bash를 사용함) 열기
• pip를 통해 uv를 설치 : pip install uv
• uv 버전 확인을 통한 설치 확인 : uv --version
• uv 프로젝트 생성 : uv init {프로젝트명}
• 해당 프로젝트를 VS Code로 열고 VS Code 내에서 터미널(Git Bash) 열기
• uv를 통해 venv 가상환경 생성 : uv venv 또는 uv venv --python {파이썬버전} (이때 3.11과 3.13이 설치되어 있었음)
• uv 가상환경 활성화 : source .venv/Scripts/activate (OS 및 터미널 종류에 따라 다름)
• uv를 통해 패키지 설치 : uv add 패키지명 (이때 streamlit과 ollama를 설치했었음)
• 참고 : uv 가상환경 비활성화 : deactivate

 

설치 후 뭔가 잘 동작하지 않아서 Python uv에서 streamlit과 ollama 의존성을 제거한 후 다시 추가했는데, 의존성을 다시 추가하는 과정에서 다음 오류가 발생했다.

error: Failed to install: typing_extensions-4.14.1-py3-none-any.whl (typing-extensions==4.14.1)

Caused by: The wheel is invalid: Metadata field Name not found

 

첫 번째 방법

해당 uv 프로젝트를 버리고 새로운 uv 프로젝트에서 다시 시작해봤지만, 의존성 추가 과정에서 같은 오류가 발생했다.

그래서 pip에서 uv를 uninstall 후 다시 install하여 이후 과정을 똑같이 진행했지만, 여전히 같은 곳에서 오류가 발생했다.

Python 버전 변경, Python 제거 후 재설치 등 다양하게 시도해봤지만, 소용이 없었다.

 

두 번째 방법

ChatGPT를 통해 정보를 알아본 결과, uv의 cache 문제일 수 있겠다는 생각이 들었다.

의존성을 추가하면 패키지 다운로드 후 설치가 이루어지기 마련인데, 터미널에서 실행하면 다운로드 과정 없이 설치만 이루어지다가 wheel 파일을 찾을 수 없다는 오류가 발생하고 있기 때문이다.

uv의 cache를 비워주기 위해 터미널에서 다음 명령어를 사용했지만, 존재하지 않는 명령어였다.

• uv pip cache purge
• 오류 발생 : error: unrecognized subcommand 'cache'

 

따라서 uv의 cache를 수동으로 비워주는 방법을 선택했다.

문제가 생길 수 있으므로, 우선 pip에서 uv를 uninstall 하고 진행했다.

• pip uninstall uv

 

이후 uv의 cache가 저장되어 있는 경로로 들어가서 파일들을 수동으로 지워주었다.

• C:\\Users\\user\\AppData\\Local\\uv\\cache 경로에 uv의 cache가 저장되어 있었다.
• 현재 uv를 제거한 상태에서 진행하고 있으므로, uv 폴더 자체를 삭제해주었다.

이후 pip를 통해 uv를 설치하는 과정부터 다시 진행해주었고, 이후 uv 의존성 추가도 문제없이 수행할 수 있었다.