# uv

[uv](https://docs.astral.sh/uv/)는 Python 프로젝트의 가상환경과 패키지를 빠르고 효율적으로 관리해주는 최신 도구입니다.

기존의 [venv](https://docs.python.org/3/library/venv.html) 방식의 가상환경 관리(virtual environment)와 [pip](https://packaging.python.org/en/latest/tutorials/installing-packages/) 방식의 패키지 관리(package manager)를 통합한 형태로, 사용성이 편리하고 속도가 무척 빠른것이 특징입니다.

[Node.js](https://nodejs.org/)에 익숙한 분이라면, 패키지 관리 도구인 [npm](https://www.npmjs.com/)과 매우 유사한 방식으로 Python 환경을 관리하는 것이라고 이해할 수 있습니다.

## 주요 기능

* 빠른 속도의 가상 환경 생성 및 관리.
* 효율적이고 빠른 패키지 설치 및 의존성 관리.
* 의존성 목록을 간단한 명령어로 관리 및 재현 가능.

## 핵심 개념

* virtual environment: 프로젝트별 독립된 Python 환경으로, 패키지 충돌을 방지.
* `pyproject.toml`: 프로젝트 메타데이터와 의존성 목록을 정의하는 표준 파일.
* `uv.lock`: 설치된 모든 패키지의 정확한 버전과 해시값을 기록하여, 다른 환경에서 동일한 환경을 재현하고 싶을때 사용.

## 사용법 예시

### 1. 새 프로젝트에서 시작하기

프로젝트 폴더를 Python 프로젝트로써 관리하게끔 합니다.

예: `myproject` 라는 프로젝트 폴더

```bash
# 폴더 생성
mkdir myproject

# 폴더로 이동
cd myproject

# uv 초기화
uv init
```

그러면 `pyproject.toml` 파일을 비롯하여 다양한 파일들을 생성해줍니다.

여기서 이제 가령, [NumPy](https://numpy.org/)가 필요하다고 합시다.

`main.py`의 내용:

```python
import numpy as np

print(np.array([1, 3]).mean())
```

uv를 사용한 패키지 설치 및 실행은 다음과 같이 `uv add` 명령어를 사용합니다:

```bash
# numpy 패키지 추가
uv add numpy
```

그러면 (없을 경우) `.venv` 폴더를 만들어서 거기에 가상환경을 설정, 설치해줍니다.

이 가상환경을 가진채로 실행을 하고 싶다면 `uv run`을 사용합니다.

```bash
# 패키지를 가진, 현재의 가상환경에서 `python main.py`를 실행
uv run python main.py
```

추가한 패키지는 프로젝트가 의존하는 패키지가 됩니다. 이 의존성을 기록해줘야합니다. 이를 "의존성을 고정(lock)한다"고 합니다.

```bash
# 의존성 고정하기
uv lock
```

그러면 `uv.lock` 파일이 생성되는것을 확인할 수 있습니다.

### 2. 기존 프로젝트에서 시작하기

기존에 uv로 관리되는 Python 프로젝트에 참여하게 되는 경우입니다.

예: `yourproject` 라는 프로젝트 폴더

```bash
# 폴더로 이동
cd yourproject
```

해당 프로젝트에 기록된 의존성을 설치해줘야 같은 환경이 구축 될 것입니다. 보통 `uv.lock` 파일이 있기 때문에, 이를 참고해서 설치를 진행하면 됩니다. uv에서는 `uv sync` 명령어를 사용합니다.

```bash
# 의존성 설치하기
uv sync
```

그럼 마찬가지로 (없다면) `.venv` 폴더가 가상환경으로써 생성되고, `uv run`을 사용할 수 있습니다.

```bash
# 현재 환경에서 실행
uv run python main.py
```

### 3. 요약

#### 새 프로젝트의 경우

```bash
# 폴더 생성
mkdir myproject

# 폴더로 이동
cd myproject

# uv 초기화
uv init

# 패키지 추가
uv add numpy

# 현재 환경에서 실행
uv run python main.py

# 의존성 고정하기
uv lock
```

#### 기존 프로젝트의 경우

```bash
# 폴더로 이동
cd yourproject

# 의존성 설치하기
uv sync

# 현재 환경에서 실행
uv run python main.py
```