[Python 시리즈 2편] Mac에서 uv로 Python 실행 환경 준비하기

1편에서 "왜 Python으로 다시 시작할까"를 정리했으니, 이제는 그 생각을 바로 실행으로 옮겨 uv(패키지와 실행을 한 번에 관리하는 CLI) 기반 환경을 세팅해 봅니다. Python을 공부하려고 마음먹었으면 가장 먼저 해야 할 일은 "내 컴퓨터에서 Python 코드가 안정적으로 실행되는 상태"를 만드는 것입니다.

이번 글에서 새로 나오는 용어

1. Homebrew: Mac에서 명령 하나로 앱을 설치하도록 도와주는 패키지 관리자
2. 가상환경: 프로젝트마다 독립된 Python 실행 공간을 만들어 버전 충돌을 막는 구조

핵심 개념

학습 메모

• 소요 시간: 30~40분
• 준비물: Homebrew가 설치된 Mac과 터미널 기본 사용 경험
• 학습 목표: uv로 프로젝트를 만들고 첫 Python 파일을 실행하기

uv를 쓰면 Python 설치, 가상환경, 패키지 설치, 실행까지 한 흐름으로 묶을 수 있습니다. 그래서 명령 체계가 단순해지고, 프로젝트를 다시 열었을 때도 환경을 재현하기 쉬워집니다.

코드로 따라하기

uv 설치하기

Homebrew를 쓴다면 아래처럼 설치할 수 있습니다.

brew install uv

설치가 끝나면 버전을 확인합니다.

uv --version

공식 설치 스크립트를 쓰는 방법도 있지만, Mac에서는 보통 Homebrew 설치가 가장 익숙합니다.

용어 정리도 간단히 짚고 갑니다.

• uv: 가상환경 생성, 패키지 설치, 실행을 모두 담당하는 올인원 CLI입니다.
• 가상환경(프로젝트 전용 실행 공간): 패키지 버전 충돌을 막아 줍니다.

프로젝트 폴더 만들기

예시로 python-playground 프로젝트를 만들어 보겠습니다.

uv init python-playground
cd python-playground

이 명령은 기본적인 Python 프로젝트 뼈대를 만들어 줍니다.

실행 환경 만들기

왜 프로젝트별 환경이 필요한가

Python 패키지는 프로젝트마다 필요한 버전이 다를 수 있습니다. 가상환경을 쓰면 프로젝트별로 설치 공간을 분리할 수 있어서 충돌이 줄어듭니다.

uv venv

그러면 .venv라는 폴더가 생깁니다.

활성화는 꼭 해야 하나

꼭 그렇지는 않습니다. uv는 uv run ... 형태로 실행하면 프로젝트 환경을 자동으로 사용합니다. 그래서 처음에는 활성화 없이 시작해도 충분합니다.

원한다면 아래처럼 직접 활성화할 수도 있습니다.

source .venv/bin/activate

활성화되면 터미널 앞부분에 .venv 표시가 보일 수 있습니다.

(.venv) MacBook-Pro python-playground $

이 상태에서는 패키지를 설치해도 현재 프로젝트 안에서만 관리됩니다.

첫 번째 Python 파일 실행하기

main.py 파일을 만들고 아래 코드를 적어 봅니다.

name = "MathBong"
print(f"Hello, {name}!")

이제 uv로 실행합니다.

uv run main.py

결과는 다음과 같습니다.

Hello, MathBong!

패키지 설치도 한번 해 보기

예를 들어 requests를 추가하고 싶다면 아래처럼 할 수 있습니다.

uv add requests

이 명령은 패키지를 설치하는 것에서 끝나지 않고, 프로젝트 의존성 정보도 함께 관리해 줍니다.

실전 예시: 리포트 요약 스크립트

rich 패키지를 설치해 터미널에서 표를 꾸며 봅니다.

uv add rich

from rich.console import Console
from rich.table import Table

console = Console()
table = Table(title="Daily Summary")
table.add_column("Task")
table.add_column("Status")

table.add_row("데이터 수집", "완료")
table.add_row("리포트 작성", "진행 중")

console.print(table)

uv로 설치부터 실행까지 한 번에 관리하면, 팀원이 프로젝트를 내려받아 uv run python main.py만 입력해도 같은 결과를 재현할 수 있습니다.

왜 중요한가

보통은 uv run이 Python 실행까지 맡기기 때문에 처음에는 python3를 직접 치지 않아도 됩니다. 필요하면 uv python install로 Python 자체를 관리할 수도 있습니다. VS Code나 Cursor 같은 에디터에서도 원리는 같으며, 인터프리터를 .venv로 맞추면 자동완성과 실행 환경이 더 잘 맞습니다.

이번 단계에서는 아래 세 가지만 되면 성공입니다.

• uv --version 확인하기
• uv init과 uv venv로 프로젝트 준비하기
• uv run main.py로 파일 실행하기

이 순서를 지키면 노트북을 초기화하더라도 같은 명령으로 환경을 다시 만들 수 있습니다.

실습

• 따라 하기: 새 폴더를 만들고 uv init, uv venv, uv run main.py 흐름을 그대로 재현합니다.
• 확장하기: rich 같은 패키지를 추가해 다른 테이블을 출력하고, 설치 명령과 결과 화면을 캡처합니다.
• 디버깅: uv run main.pyy처럼 파일 이름을 일부러 틀린 뒤 오류 메시지를 읽고, 올바른 경로로 고쳐 실행합니다.
• 완료 기준: 새 프로젝트에서 uv run 출력이 정상적으로 나오고, 명령 기록을 메모해 둘 때입니다.

마무리

Python 공부는 문법부터 외우는 것보다, 먼저 실행 환경을 스스로 다룰 수 있는 상태를 만드는 것이 중요합니다. uv를 기준으로 시작해 두면 이후에는 패키지 추가, 실행, 프로젝트 재현까지 훨씬 단순해집니다.

다음 글에서는 변수, 자료형, 입력-출력 흐름을 아주 짧은 예제로 묶어서 Python 문법 감각을 본격적으로 잡아보겠습니다.