# uv를 이용한 독립 실행형 Python 스크립트 만들기

> Clean Markdown view of GeekNews topic #20046. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=20046](https://news.hada.io/topic?id=20046)
- GeekNews Markdown: [https://news.hada.io/topic/20046.md](https://news.hada.io/topic/20046.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2025-03-31T09:46:52+09:00
- Updated: 2025-03-31T09:46:52+09:00
- Original source: [blog.dusktreader.dev](http://blog.dusktreader.dev/2025/03/29/self-contained-python-scripts-with-uv/)
- Points: 5
- Comments: 0

## Summary

`uv`를 사용하면 Python 스크립트를 독립 실행형으로 만들어 의존성 설치 없이 즉시 실행할 수 있습니다. `uv`는 격리된 실행 환경을 제공하여 스크립트 내부에 의존성을 명시하고, 자동으로 임시 가상환경을 생성하여 필요한 패키지를 설치하고 실행합니다. 이를 통해 복잡한 사전 설정 없이도 스크립트 실행과 의존성 관리가 가능하며, 시스템 환경을 오염시키지 않고 다른 사람에게 쉽게 공유할 수 있습니다.

## Topic Body

- Python 스크립트에 `uv`를 활용해 **의존성 설치 없이 즉시 실행 가능한 독립 실행형 스크립트**를 만드는 방법  
- Go 프로젝트에서 API 테스트용으로 Python 스크립트를 사용하는 상황에서 나온 실용적 접근법임  
  
### 기존 방식의 한계  
  
- `httpx`, `IPython`, `loguru` 등의 패키지를 사용하는 Python 스크립트를 실행하려면 다음 중 하나를 선택해야 했음  
  - 시스템 Python에 직접 패키지 설치  
  - 가상환경 생성 및 패키지 설치 후 실행  
- 두 방법 모두 번거롭고, 시스템 환경에 영향을 줄 수 있으며, 타인에게 공유 시 설명이 길어지는 문제가 있음  
  
### uv로 간편한 스크립트 실행  
  
- [`uv`](https://github.com/astral-sh/uv)는 Python 패키지 관리자이자 pip 대체 도구로, **격리된 실행 환경**에서 Python 스크립트를 실행 가능하게 해줌  
- `# /// script` 주석을 통해 **스크립트 내부에 의존성 정보를 명시**할 수 있음  
  ```python  
  # /// script  
  # dependencies = ["ipython", "httpx", "loguru"]  
  # ///  
  ```  
- 위 설정이 포함된 스크립트는 다음 명령으로 실행 가능:  
  ```bash  
  uv run jam_users.py  
  ```  
- uv는 자동으로 임시 가상환경 생성, 필요한 패키지 설치, 그리고 스크립트 실행까지 한 번에 처리함  
  
### 실행 가능한 스크립트로 만들기  
- 일반 Python 스크립트처럼 #!/usr/bin/env python을 이용해 실행 가능하게 만들 수 있지만, 이 방식은 uv의 script 주석을 인식하지 못함  
- 대신 아래처럼 shebang에 uv 명령을 직접 넣어 해결할 수 있음  
  ```bash  
  #!/usr/bin/env -S uv run --script  
  # /// script  
  # dependencies = ["ipython", "httpx", "loguru"]  
  # ///  
  ```  
- 이 방식은 chmod +x 후 직접 실행 가능하며, 다른 유닉스 시스템에서도 uv만 있으면 그대로 작동함:  
  ```bash  
  ./jam_users.py  
  ```  
### 장점 및 활용도  
- uv 방식은 다른 사람에게 스크립트를 전달할 때 매우 유용함  
- 복잡한 사전 설정 없이도 필요한 패키지와 환경이 자동으로 세팅됨  
- 시스템 Python이나 글로벌 환경을 오염시키지 않음  
- 스크립트 하나로 실행과 의존성 관리가 모두 해결됨  
  
> 필자는 과거에 다른 사람에게 Python 스크립트를 전달할 때 설치 설명이 복잡했던 경험이 있었지만, 이제는 uv를 통해 이 문제를 간단히 해결 가능하다고 설명함  
  
- 작은 테스트 스크립트 뿐 아니라 실무용 자동화 스크립트에서도 효과적임

## Comments



_No public comments on this page._