# 설치

시작하기 전에, 적절한 패키지를 설치하여 환경을 설정해야 합니다.

`huggingface_hub`은 **Python 3.10+**에서 테스트됩니다.

## pip으로 설치

`huggingface_hub`을 [가상 환경](https://docs.python.org/3/library/venv.html)에 설치하는 것을 강력히 권장합니다. Python 가상 환경에 익숙하지 않다면 이 [가이드](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)를 참고하세요. 가상 환경은 서로 다른 프로젝트를 관리하기 쉽고, 의존성 간의 호환성 문제를 피하는 데 도움이 됩니다.

프로젝트 디렉터리에서 가상 환경을 만들어 시작합니다:

```bash
python -m venv .venv
```

가상 환경을 활성화합니다. Linux 및 macOS의 경우:

```bash
source .venv/bin/activate
```

Windows에서 가상 환경 활성화:

```bash
.venv/Scripts/activate
```

이제 [PyPi 레지스트리에서](https://pypi.org/project/huggingface-hub/) `huggingface_hub`를 설치할 준비가 되었습니다:

```bash
pip install --upgrade huggingface_hub
```

완료되면 [설치 확인](#check-installation)이 올바르게 작동하는지 확인하세요.

### 선택적 종속성 설치

`huggingface_hub`의 일부 종속성은 `huggingface_hub`의 핵심 기능을 실행하는 데 필수적이지 않기 때문에 [선택 사항](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies)입니다. 그러나 선택적 종속성이 설치되지 않으면 `huggingface_hub`의 일부 기능을 사용할 수 없을 수 있습니다.

`pip`를 통해 선택적 의존성을 설치할 수 있습니다:
```bash
# Install dependencies for both torch-specific and MCP-specific features.
pip install 'huggingface_hub[mcp,torch]'
```

`huggingface_hub`의 선택적 의존성 목록은 다음과 같습니다:
- `fastai`, `torch`: 프레임워크별 기능을 실행하는 데 필요한 종속성.
- `dev`: 라이브러리에 기여하는 데 필요한 의존성입니다. `testing`(테스트 실행), `typing`(타입 체커 실행), `quality`(린터 실행)을 포함합니다.

### 소스에서 설치

일부 경우에는 `huggingface_hub`를 소스에서 직접 설치하는 것이 유용합니다. 이렇게 하면 최신 안정 버전 대신 가장 최신의 `main` 버전을 사용할 수 있습니다. `main` 버전은 최신 개발 동향을 따라가기에 유용하며, 예를 들어 이전 공식 릴리스 이후 버그가 수정되었지만 새로운 릴리스가 아직 배포되지 않은 경우에 해당합니다.

그러나 이는 `main` 버전이 항상 안정적이지 않을 수 있음을 의미합니다. `main` 버전이 정상적으로 작동하도록 최선을 다하고 있으며, 대부분의 문제는 보통 몇 시간에서 하루 이내에 해결됩니다. 문제가 발생하면 Issue를 열어 주시면 더 빠르게 수정할 수 있습니다!

```bash
pip install git+https://github.com/huggingface/huggingface_hub
```

소스에서 설치할 때 특정 브랜치를 지정할 수도 있습니다. 아직 병합되지 않은 새로운 기능이나 버그 수정 사항을 테스트하려는 경우 유용합니다:

```bash
pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch
```

완료되면 [설치 확인](#check-installation)이 올바르게 작동하는지 확인하세요.

### 수정 가능한 설치

소스에서 설치하면 [편집 가능한 설치](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs)를 설정할 수 있습니다. `huggingface_hub`에 기여할 계획이 있고 코드 변경 사항을 테스트해야 하는 경우 더 고급 수준의 설치 방법입니다. 기계에 `huggingface_hub`의 로컬 복사본을 클론해야 합니다.

```bash
# First, clone repo locally
git clone https://github.com/huggingface/huggingface_hub.git

# Then, install with -e flag
cd huggingface_hub
pip install -e .
```

이 명령어는 저장소를 클론한 폴더와 Python 라이브러리 경로를 연결합니다. 이제 Python은 일반적인 라이브러리 경로 외에도 클론한 폴더를 검색합니다. 예를 들어, Python 패키지가 일반적으로 `./.venv/lib/python3.13/site-packages/`에 설치되어 있다면, Python은 `./huggingface_hub/`에 클론한 폴더도 검색합니다.

## Hugging Face CLI 설치 

Python 환경을 건드리지 않고 `hf` CLI를 설정하려면 원라이너 설치기를 사용하세요:

macOS 및 Linux에서:

```bash
curl -LsSf https://hf.co/cli/install.sh | bash
```

Windows에서:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
```

기존 설치 환경을 업그레이드하려면 `hf update`를 실행하세요. 이 명령은 `hf`가 어떤 방식으로 설치되었는지(스탠드얼론 설치 프로그램, Homebrew, 또는 pip)를 감지하고 그에 맞는 명령을 실행합니다.

## conda로 설치

conda-forge channel에 더 익숙하시다면, [conda-forge channel](https://anaconda.org/conda-forge/huggingface_hub)을 통해 `huggingface_hub`를 설치할 수 있습니다:

```bash
conda install -c conda-forge huggingface_hub
```

완료되면 [설치 확인](#check-installation)이 올바르게 작동하는지 확인하세요.

## 설치 확인

설치 후 다음 명령을 실행하여 `huggingface_hub`이 정상적으로 작동하는지 확인하세요:

```bash
python -c "from huggingface_hub import model_info; print(model_info('gpt2'))"
```

이 명령은 Hub에서 [gpt2](https://huggingface.co/gpt2) 모델에 대한 정보를 가져옵니다. 출력은 다음과 같아야 합니다:

```text
Model Name: gpt2
Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space']
Task: text-generation
```

## Windows 제한 사항

좋은 ML을 모든 곳에서 민주화하려는 목표를 가지고, `huggingface_hub`는 크로스 플랫폼 라이브러리로 구축되었으며, 특히 Unix 기반 시스템과 Windows 시스템 모두에서 올바르게 작동하도록 설계되었습니다. 그러나 Windows에서 실행될 때 `huggingface_hub`에는 몇 가지 제한 사항이 있습니다. 알려진 문제의 포괄적인 목록은 다음과 같습니다. 문서화되지 않은 문제를 발견하신 경우, [Github에서 이슈를 열어](https://github.com/huggingface/huggingface_hub/issues/new/choose) 알려 주시기 바랍니다.

- `huggingface_hub`의 캐시 시스템은 다운로드된 파일을 효율적으로 캐시하기 위해 심볼릭 링크에 의존합니다
Hub에서 가져옵니다. Windows에서는 심볼릭 링크를 활성화하려면 개발자 모드를 활성화하거나 스크립트를 관리자 권한으로 실행해야 합니다. 활성화되지 않은 경우에도 캐시 시스템은 작동하지만 최적화되지 않은 방식으로 작동합니다. 자세한 내용은 [캐시 제한 사항](./guides/manage-cache#limitations) 섹션을 참고하세요.
- Hub의 파일 경로에는 특수 문자(예: `"path/to?/my/file"`)가 포함될 수 있습니다. Windows는
more restrictive on [special characters](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names) which makes it impossible to download those files on Windows. Hopefully this is a rare case. Please reach out to the repo owner if you think this is a mistake or to us to figure out a solution.

## 다음 단계

`huggingface_hub`이 컴퓨터에 올바르게 설치되면, [환경 변수를 구성](package_reference/environment_variables)하거나 [가이드 중 하나를 확인](guides/overview)하여 시작할 수 있습니다.

