최근에 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 의존성 추가도 문제없이 수행할 수 있었다.
'Python' 카테고리의 다른 글
| Python의 yield 키워드를 알아보자 (0) | 2025.09.29 |
|---|---|
| Python 형 변환 간단히 정리 (0) | 2022.04.24 |