🌐 Update translations for ko (update-outdated)

2026-09-24 12:25:13 -04:00 · 2026-08-01 06:06:56 +00:00
1 parent 95f8322ee1
commit 0df08458b8
@@ -125,7 +125,7 @@ def read_url():
 또한 표준 기반의 사용자 인터페이스 도구를 통합하기:

 * [Swagger UI](https://github.com/swagger-api/swagger-ui)
-* [ReDoc](https://github.com/Rebilly/ReDoc)
+* [ReDoc](https://github.com/Redocly/redoc)

 이 두 가지는 꽤 대중적이고 안정적이기 때문에 선택되었습니다. 하지만 간단히 검색해보면 OpenAPI를 위한 대안 UI가 수십 가지나 있다는 것을 알 수 있습니다(**FastAPI**와 함께 사용할 수 있습니다).

@@ -237,7 +237,7 @@ serialization과 validation을 정의하는 동일한 코드로부터 OpenAPI sc

 ///

-### [NestJS](https://nestjs.com/) (그리고 [Angular](https://angular.io/)) { #nestjs-and-angular }
+### [NestJS](https://nestjs.com/) (그리고 [Angular](https://angular.dev/)) { #nestjs-and-angular }

 이건 Python도 아닙니다. NestJS는 Angular에서 영감을 받은 JavaScript(TypeScript) NodeJS framework입니다.

@@ -337,7 +337,7 @@ OpenAPI나 JSON Schema 같은 표준을 기반으로 하지 않았기 때문에

 /// note | 참고

-Hug는 Timothy Crosley가 만들었습니다. Python 파일에서 import를 자동으로 정렬하는 훌륭한 도구인 [`isort`](https://github.com/timothycrosley/isort)의 제작자이기도 합니다.
+Hug는 Timothy Crosley가 만들었습니다. Python 파일에서 import를 자동으로 정렬하는 훌륭한 도구인 [`isort`](https://github.com/PyCQA/isort)의 제작자이기도 합니다.

 ///

@@ -401,7 +401,7 @@ APIStar는 Tom Christie가 만들었습니다. 다음을 만든 사람과 동일

 ## **FastAPI**가 사용하는 것 { #used-by-fastapi }

-### [Pydantic](https://docs.pydantic.dev/) { #pydantic }
+### [Pydantic](https://pydantic.dev/docs/) { #pydantic }

 Pydantic은 Python type hints를 기반으로 데이터 검증, serialization, 문서화(JSON Schema 사용)를 정의하는 라이브러리입니다.

@@ -417,7 +417,7 @@ Marshmallow와 비교할 수 있습니다. 다만 benchmark에서 Marshmallow보

 ///

-### [Starlette](https://www.starlette.dev/) { #starlette }
+### [Starlette](https://starlette.dev/) { #starlette }

 Starlette는 경량 <dfn title="비동기 Python 웹 애플리케이션을 구축하기 위한 새로운 표준">ASGI</dfn> framework/toolkit으로, 고성능 asyncio 서비스를 만들기에 이상적입니다.

@@ -462,7 +462,7 @@ ASGI는 Django 코어 팀 멤버들이 개발 중인 새로운 "표준"입니다

 ///

-### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn }
+### [Uvicorn](https://uvicorn.dev) { #uvicorn }

 Uvicorn은 uvloop과 httptools로 구축된 초고속 ASGI 서버입니다.

@@ -1,299 +1,11 @@
 # 환경 변수 { #environment-variables }

+**환경 변수**(또는 **env var**라고도 합니다)는 파이썬 코드 바깥인 운영 체제에 존재하는 값이며, 애플리케이션과 다른 프로그램에서 읽을 수 있습니다.

-/// tip | 팁
+FastAPI 애플리케이션은 데이터베이스 URL, 이메일 자격 증명, 비밀 키와 같은 설정에 환경 변수를 일반적으로 사용합니다.

-만약 "환경 변수"가 무엇이고, 어떻게 사용하는지 알고 계시다면, 이 챕터를 스킵하셔도 좋습니다.
+[설정 및 환경 변수](advanced/settings.md)에서 애플리케이션 설정에 환경 변수를 사용하는 방법을 배우게 됩니다.

-///
+## 더 알아보기 { #learn-more }

-환경 변수(또는 "**env var**"라고도 합니다)는 파이썬 코드의 **바깥**인, **운영 체제**에 존재하는 변수이며, 파이썬 코드(또는 다른 프로그램에서도)에서 읽을 수 있습니다.
-
-환경 변수는 애플리케이션 **설정**을 처리하거나, 파이썬의 **설치** 과정의 일부로 유용할 수 있습니다.
-
-## 환경 변수를 만들고 사용하기 { #create-and-use-env-vars }
-
-파이썬 없이도, **셸 (터미널)** 에서 환경 변수를 **생성** 하고 사용할 수 있습니다.
-
-//// tab | Linux, macOS, Windows Bash
-
-<div class="termy">
-
-```console
-// 환경 변수 MY_NAME을 다음과 같이 생성할 수 있습니다
-$ export MY_NAME="Wade Wilson"
-
-// 그런 다음 다른 프로그램과 함께 사용할 수 있습니다. 예:
-$ echo "Hello $MY_NAME"
-
-Hello Wade Wilson
-```
-
-</div>
-
-////
-
-//// tab | Windows PowerShell
-
-<div class="termy">
-
-```console
-// 환경 변수 MY_NAME 생성
-$ $Env:MY_NAME = "Wade Wilson"
-
-// 다른 프로그램과 함께 사용하기. 예:
-$ echo "Hello $Env:MY_NAME"
-
-Hello Wade Wilson
-```
-
-</div>
-
-////
-
-## 파이썬에서 env var 읽기 { #read-env-vars-in-python }
-
-파이썬 **바깥**인 터미널에서(또는 다른 어떤 방법으로든) 환경 변수를 만들고, 그런 다음 **파이썬에서 읽을 수 있습니다**.
-
-예를 들어 다음과 같은 `main.py` 파일이 있다고 합시다:
-
-```Python hl_lines="3"
-import os
-
-name = os.getenv("MY_NAME", "World")
-print(f"Hello {name} from Python")
-```
-
-/// tip | 팁
-
-[`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) 의 두 번째 인자는 반환할 기본값입니다.
-
-제공하지 않으면 기본값은 `None`이며, 여기서는 사용할 기본값으로 `"World"`를 제공합니다.
-
-///
-
-그러면 해당 파이썬 프로그램을 다음과 같이 호출할 수 있습니다:
-
-//// tab | Linux, macOS, Windows Bash
-
-<div class="termy">
-
-```console
-// 여기서는 아직 환경 변수를 설정하지 않습니다
-$ python main.py
-
-// 환경 변수를 설정하지 않았으므로 기본값이 사용됩니다
-
-Hello World from Python
-
-// 하지만 먼저 환경 변수를 생성하면
-$ export MY_NAME="Wade Wilson"
-
-// 그리고 프로그램을 다시 실행하면
-$ python main.py
-
-// 이제 환경 변수를 읽을 수 있습니다
-
-Hello Wade Wilson from Python
-```
-
-</div>
-
-////
-
-//// tab | Windows PowerShell
-
-<div class="termy">
-
-```console
-// 여기서는 아직 환경 변수를 설정하지 않습니다
-$ python main.py
-
-// 환경 변수를 설정하지 않았으므로 기본값이 사용됩니다
-
-Hello World from Python
-
-// 하지만 먼저 환경 변수를 생성하면
-$ $Env:MY_NAME = "Wade Wilson"
-
-// 그리고 프로그램을 다시 실행하면
-$ python main.py
-
-// 이제 환경 변수를 읽을 수 있습니다
-
-Hello Wade Wilson from Python
-```
-
-</div>
-
-////
-
-환경변수는 코드 바깥에서 설정될 수 있지만, 코드에서 읽을 수 있고, 나머지 파일과 함께 저장(`git`에 커밋)할 필요가 없으므로, 구성이나 **설정** 에 사용하는 것이 일반적입니다.
-
-또한 **특정 프로그램 호출**에 대해서만 사용할 수 있는 환경 변수를 만들 수도 있는데, 해당 프로그램에서만 사용할 수 있고, 해당 프로그램이 실행되는 동안만 사용할 수 있습니다.
-
-그렇게 하려면 프로그램 바로 앞, 같은 줄에 환경 변수를 만들어야 합니다:
-
-<div class="termy">
-
-```console
-// 이 프로그램 호출을 위해 같은 줄에서 환경 변수 MY_NAME 생성
-$ MY_NAME="Wade Wilson" python main.py
-
-// 이제 환경 변수를 읽을 수 있습니다
-
-Hello Wade Wilson from Python
-
-// 이후에는 해당 환경 변수가 존재하지 않습니다
-$ python main.py
-
-Hello World from Python
-```
-
-</div>
-
-/// tip | 팁
-
-[The Twelve-Factor App: Config](https://12factor.net/config) 에서 좀 더 자세히 알아볼 수 있습니다.
-
-///
-
-## 타입과 검증 { #types-and-validation }
-
-이 환경변수들은 오직 **텍스트 문자열**로만 처리할 수 있습니다. 텍스트 문자열은 파이썬 외부에 있으며 다른 프로그램 및 나머지 시스템(그리고 Linux, Windows, macOS 같은 서로 다른 운영 체제에서도)과 호환되어야 합니다.
-
-즉, 파이썬에서 환경 변수로부터 읽은 **모든 값**은 **`str`**이 되고, 다른 타입으로의 변환이나 검증은 코드에서 수행해야 합니다.
-
-**애플리케이션 설정**을 처리하기 위한 환경 변수 사용에 대한 자세한 내용은 [고급 사용자 가이드 - 설정 및 환경 변수](./advanced/settings.md) 에서 확인할 수 있습니다.
-
-## `PATH` 환경 변수 { #path-environment-variable }
-
-**`PATH`**라고 불리는, **특별한** 환경변수가 있습니다. 운영체제(Linux, macOS, Windows)에서 실행할 프로그램을 찾기위해 사용됩니다.
-
-변수 `PATH`의 값은 Linux와 macOS에서는 콜론 `:`, Windows에서는 세미콜론 `;`으로 구분된 디렉토리로 구성된 긴 문자열입니다.
-
-예를 들어, `PATH` 환경 변수는 다음과 같습니다:
-
-//// tab | Linux, macOS
-
-```plaintext
-/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
-```
-
-이는 시스템이 다음 디렉토리에서 프로그램을 찾아야 함을 의미합니다:
-
-* `/usr/local/bin`
-* `/usr/bin`
-* `/bin`
-* `/usr/sbin`
-* `/sbin`
-
-////
-
-//// tab | Windows
-
-```plaintext
-C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32
-```
-
-이는 시스템이 다음 디렉토리에서 프로그램을 찾아야 함을 의미합니다:
-
-* `C:\Program Files\Python312\Scripts`
-* `C:\Program Files\Python312`
-* `C:\Windows\System32`
-
-////
-
-터미널에 **명령어**를 입력하면 운영 체제는 `PATH` 환경 변수에 나열된 **각 디렉토리**에서 프로그램을 **찾습니다.**
-
-예를 들어 터미널에 `python`을 입력하면 운영 체제는 해당 목록의 **첫 번째 디렉토리**에서 `python`이라는 프로그램을 찾습니다.
-
-찾으면 **사용합니다**. 그렇지 않으면 **다른 디렉토리**에서 계속 찾습니다.
-
-### 파이썬 설치와 `PATH` 업데이트 { #installing-python-and-updating-the-path }
-
-파이썬을 설치할 때, 아마 `PATH` 환경 변수를 업데이트 할 것이냐고 물어봤을 겁니다.
-
-//// tab | Linux, macOS
-
-파이썬을 설치하고 그것이 `/opt/custompython/bin` 디렉토리에 있다고 가정해 보겠습니다.
-
-`PATH` 환경 변수를 업데이트하도록 "예"라고 하면 설치 관리자가 `/opt/custompython/bin`을 `PATH` 환경 변수에 추가합니다.
-
-다음과 같이 보일 수 있습니다:
-
-```plaintext
-/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin
-```
-
-이렇게 하면 터미널에 `python`을 입력할 때, 시스템이 `/opt/custompython/bin`(마지막 디렉토리)에서 파이썬 프로그램을 찾아 사용합니다.
-
-////
-
-//// tab | Windows
-
-파이썬을 설치하고 그것이 `C:\opt\custompython\bin` 디렉토리에 있다고 가정해 보겠습니다.
-
-`PATH` 환경 변수를 업데이트하도록 "예"라고 하면 설치 관리자가 `C:\opt\custompython\bin`을 `PATH` 환경 변수에 추가합니다.
-
-```plaintext
-C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin
-```
-
-이렇게 하면 터미널에 `python`을 입력할 때, 시스템이 `C:\opt\custompython\bin`(마지막 디렉토리)에서 파이썬 프로그램을 찾아 사용합니다.
-
-////
-
-그래서, 다음과 같이 입력한다면:
-
-<div class="termy">
-
-```console
-$ python
-```
-
-</div>
-
-//// tab | Linux, macOS
-
-시스템은 `/opt/custompython/bin`에서 `python` 프로그램을 **찾아** 실행합니다.
-
-다음과 같이 입력하는 것과 거의 같습니다:
-
-<div class="termy">
-
-```console
-$ /opt/custompython/bin/python
-```
-
-</div>
-
-////
-
-//// tab | Windows
-
-시스템은 `C:\opt\custompython\bin\python`에서 `python` 프로그램을 **찾아** 실행합니다.
-
-다음과 같이 입력하는 것과 거의 같습니다:
-
-<div class="termy">
-
-```console
-$ C:\opt\custompython\bin\python
-```
-
-</div>
-
-////
-
-이 정보는 [가상 환경](virtual-environments.md) 에 대해 알아볼 때 유용할 것입니다.
-
-## 결론 { #conclusion }
-
-이 문서를 통해 **환경 변수**가 무엇이고 파이썬에서 어떻게 사용하는지 기본적으로 이해하셨을 겁니다.
-
-또한 [환경 변수에 대한 위키피디아](https://en.wikipedia.org/wiki/Environment_variable)에서 이에 대해 자세히 알아볼 수 있습니다.
-
-많은 경우에서, 환경 변수가 어떻게 유용하고 적용 가능한지 바로 명확하게 알 수는 없습니다. 하지만 개발할 때 다양한 시나리오에서 계속 나타나므로 이에 대해 아는 것이 좋습니다.
-
-예를 들어, 다음 섹션인 [가상 환경](virtual-environments.md)에서 이 정보가 필요합니다.
+환경 변수를 만들고 읽는 방법과 `PATH` 환경 변수가 작동하는 방식을 포함하여, 자세한 크로스 플랫폼 설명은 [환경 변수 가이드](https://tiangolo.com/guides/environment-variables/)를 읽어보세요.
@@ -1,8 +1,8 @@
 # FastAPI CLI { #fastapi-cli }

-**FastAPI <abbr title="command line interface - 명령줄 인터페이스">CLI</abbr>**는 FastAPI 애플리케이션을 서빙하고, FastAPI 프로젝트를 관리하는 등 다양한 작업에 사용할 수 있는 커맨드 라인 프로그램입니다.
+**FastAPI <abbr title="command line interface - 명령줄 인터페이스">CLI</abbr>**는 FastAPI 애플리케이션을 서빙하고, FastAPI 프로젝트를 관리하는 등 다양한 작업에 사용할 수 있는 명령줄 프로그램입니다.

-FastAPI를 설치하면(예: `pip install "fastapi[standard]"`) 터미널에서 실행할 수 있는 커맨드 라인 프로그램이 함께 제공됩니다.
+프로젝트에 FastAPI를 추가하면(예: `uv add "fastapi[standard]"`) 터미널에서 실행할 수 있는 명령줄 프로그램이 함께 제공됩니다.

 개발용으로 FastAPI 애플리케이션을 실행하려면 `fastapi dev` 명령어를 사용할 수 있습니다:

@@ -41,7 +41,7 @@ $ <font color="#4E9A06">fastapi</font> dev
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Started reloader process <b>[</b><font color="#34E2E2"><b>383138</b></font><b>]</b> using WatchFiles
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Started server process <b>[</b><font color="#34E2E2"><b>383153</b></font><b>]</b>
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Waiting for application startup.
-     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Application startup complete.
+     <span style="background-color:#007166"><font color="#007166"><font color="#D3D7CF"> INFO </font></font></span>  Application startup complete.
 ```

 </div>
@@ -52,22 +52,22 @@ $ <font color="#4E9A06">fastapi</font> dev

 ///

-내부적으로 **FastAPI CLI**는 고성능의, 프로덕션에 적합한 ASGI 서버인 [Uvicorn](https://www.uvicorn.dev)을 사용합니다. 😎
+내부적으로 **FastAPI CLI**는 고성능의, 프로덕션에 적합한 ASGI 서버인 [Uvicorn](https://uvicorn.dev)을 사용합니다. 😎

-`fastapi` CLI는 기본적으로 실행할 FastAPI 앱을 자동으로 감지하려고 시도합니다. `main.py` 파일 안의 `app`이라는 객체(또는 몇 가지 변형)가 있다고 가정합니다.
+`fastapi` CLI는 기본적으로 실행할 FastAPI 애플리케이션을 자동으로 감지하려고 시도합니다. `main.py` 파일 안의 `app`이라는 객체(또는 몇 가지 변형)가 있다고 가정합니다.

-하지만 사용할 앱을 명시적으로 구성할 수도 있습니다.
+하지만 사용할 애플리케이션을 명시적으로 구성할 수도 있습니다.

-## `pyproject.toml`에서 앱 `entrypoint` 구성하기 { #configure-the-app-entrypoint-in-pyproject-toml }
+## `pyproject.toml`에서 애플리케이션 `entrypoint` 구성하기 { #configure-the-app-entrypoint-in-pyproject-toml }

-`pyproject.toml` 파일에서 앱이 어디에 있는지 다음과 같이 구성할 수 있습니다:
+`pyproject.toml` 파일에서 애플리케이션이 어디에 있는지 다음과 같이 구성할 수 있습니다:

 ```toml
 [tool.fastapi]
 entrypoint = "main:app"
 ```

-이 `entrypoint`는 `fastapi` 명령어에 다음과 같이 앱을 임포트하라고 알려줍니다:
+이 `entrypoint`는 `fastapi` 명령어에 다음과 같이 애플리케이션을 임포트하라고 알려줍니다:

 ```python
 from main import app
@@ -97,16 +97,16 @@ from backend.main import app

 ### 경로 또는 `--entrypoint` CLI 옵션과 함께 `fastapi dev` { #fastapi-dev-with-path-or-with-entrypoint-cli-option }

-`fastapi dev` 명령어에 파일 경로를 전달할 수도 있으며, 그러면 사용할 FastAPI 앱 객체를 추정합니다:
+`fastapi dev` 명령어에 파일 경로를 전달할 수도 있으며, 그러면 사용할 FastAPI 애플리케이션 객체를 추정합니다:

 ```console
-$ fastapi dev main.py
+$ uv run fastapi dev main.py
 ```

 또는, `fastapi dev` 명령어에 `--entrypoint` 옵션을 전달할 수도 있습니다:

 ```console
-$ fastapi dev --entrypoint main:app
+$ uv run fastapi dev --entrypoint main:app
 ```

 하지만 매번 `fastapi` 명령어를 호출할 때 올바른 경로\entrypoint를 전달하는 것을 기억해야 합니다.
@@ -119,6 +119,10 @@ $ fastapi dev --entrypoint main:app

 기본적으로 **auto-reload**가 활성화되어 코드에 변경이 생기면 서버를 자동으로 다시 로드합니다. 이는 리소스를 많이 사용하며, 비활성화했을 때보다 안정성이 떨어질 수 있습니다. 개발 환경에서만 사용해야 합니다. 또한 컴퓨터가 자신과만 통신하기 위한(`localhost`) IP인 `127.0.0.1`에서 연결을 대기합니다.

+애플리케이션을 임포트하기 전에, `fastapi dev`는 `FASTAPI_ENV` 환경 변수를 `development`로 설정합니다. `FASTAPI_ENV`가 이미 설정되어 있다면 기존 값이 유지됩니다. 이를 통해 애플리케이션 시작 코드는 개발에 친화적인 동작을 선택할 수 있으면서도, `staging` 같은 애플리케이션별 환경을 제공할 수 있습니다.
+
+관례적인 `FASTAPI_ENV` 값은 `development`와 `production`입니다. 현재 `fastapi run`은 `FASTAPI_ENV`를 변경하지 않으므로, 애플리케이션이 프로덕션 모드를 감지해야 한다면 명시적으로 설정하세요.
+
 ## `fastapi run` { #fastapi-run }

 `fastapi run`을 실행하면 프로덕션 모드로 FastAPI가 시작됩니다.
@@ -19,7 +19,7 @@

 ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png)

-* [**ReDoc**](https://github.com/Rebilly/ReDoc)을 이용한 대체 API 문서화.
+* [**ReDoc**](https://github.com/Redocly/redoc)을 이용한 대체 API 문서화.

 ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png)

@@ -159,7 +159,7 @@ FastAPI는 사용하기 매우 쉽지만, 매우 강력한 <dfn title='또한

 ## Starlette 기능 { #starlette-features }

-**FastAPI**는 [**Starlette**](https://www.starlette.dev/)와 완전히 호환되며(또한 이를 기반으로 합니다). 따라서 추가로 가지고 있는 Starlette 코드도 모두 동작합니다.
+**FastAPI**는 [**Starlette**](https://starlette.dev/)와 완전히 호환되며(또한 이를 기반으로 합니다). 따라서 추가로 가지고 있는 Starlette 코드도 모두 동작합니다.

 `FastAPI`는 실제로 `Starlette`의 하위 클래스입니다. 그래서 Starlette을 이미 알고 있거나 사용하고 있다면, 대부분의 기능이 같은 방식으로 동작할 것입니다.

@@ -177,7 +177,7 @@ FastAPI는 사용하기 매우 쉽지만, 매우 강력한 <dfn title='또한

 ## Pydantic 기능 { #pydantic-features }

-**FastAPI**는 [**Pydantic**](https://docs.pydantic.dev/)과 완벽하게 호환되며(또한 이를 기반으로 합니다). 따라서 추가로 가지고 있는 Pydantic 코드도 모두 동작합니다.
+**FastAPI**는 [**Pydantic**](https://pydantic.dev/docs/)과 완벽하게 호환되며(또한 이를 기반으로 합니다). 따라서 추가로 가지고 있는 Pydantic 코드도 모두 동작합니다.

 데이터베이스를 위한 <abbr title="Object-Relational Mapper - 객체-관계 매퍼">ORM</abbr>, <abbr title="Object-Document Mapper - 객체-문서 매퍼">ODM</abbr>과 같은, Pydantic을 기반으로 하는 외부 라이브러리도 포함합니다.

@@ -1,6 +1,5 @@
 # 도움 { #help }

-
 FastAPI를 돕거나 FastAPI에 대한 도움을 받고 싶으신가요?

 아주 간단하게 돕고 도움을 받을 수 있는 방법이 있습니다.
@@ -46,30 +45,16 @@ FastAPI와 friends에 대한 소식을 공유할 때 알림을 받으려면, 개
 * [**Bluesky**의 @tiangolo.com](https://bsky.app/profile/tiangolo.com)
 * [**LinkedIn**의 @tiangolo](https://www.linkedin.com/in/tiangolo/).

-## GitHub에서 질문으로 다른 사람 돕기 { #help-others-with-questions-in-github }
-
-[GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered)에서 다른 사람들의 질문에 도움을 줄 수 있습니다.
-
-많은 경우, 이미 그 질문에 대한 답을 알고 있을 수 있습니다. 🤓
-
-많은 사람들의 질문을 도와주면, 공식 [FastAPI 전문가](fastapi-people.md#fastapi-experts)가 됩니다. 🎉
-
-가장 중요한 점은: 친절하려고 노력하는 것입니다. 🤗
-
-### 도움 주는 방법 { #how-to-help }
-
-여기 있는 [도움 주는 방법 가이드](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github)를 따라 주세요.
-
 ## 질문하기 { #ask-questions }

 GitHub 저장소에서 [새 질문을 생성](https://github.com/fastapi/fastapi/discussions/new?category=questions)할 수 있습니다. 예를 들면:

-* **질문**을 하거나 **문제**에 대해 묻기
-* 새로운 **기능** 제안하기
+* **질문**을 하거나 **문제**에 대해 묻기.
+* 새로운 **기능** 제안하기.

 ## 채팅에 참여하기 { #join-the-chat }

-👥 [Discord 채팅 서버](https://discord.gg/VQjSZaeJmf) 👥 에 참여해서 FastAPI 커뮤니티의 다른 사람들과 어울리세요.
+👥 [Discord 채팅 서버](https://discord.com/invite/VQjSZaeJmf) 👥 에 참여해서 FastAPI 커뮤니티의 다른 사람들과 어울리세요.

 /// tip | 팁

@@ -81,8 +66,14 @@ GitHub 저장소에서 [새 질문을 생성](https://github.com/fastapi/fastapi

 ### 질문을 위해 채팅을 사용하지 마세요 { #dont-use-the-chat-for-questions }

-채팅은 더 자유로운 대화를 허용하므로, 너무 일반적이거나 답변하기 어려운 질문을 하게 되어 답변을 받지 못할 수 있습니다.
+채팅은 더 자유로운 대화를 허용하므로, 너무 일반적이거나 답변하기 어려운 질문을 하게 되어 답변을 받지 못할 수 있음을 기억하세요.

 GitHub에서는 템플릿이 올바른 질문을 작성하도록 안내하여, 더 쉽게 좋은 답변을 받거나 심지어 질문하기 전에 스스로 문제를 해결할 수 있습니다.

 또한 채팅 시스템의 대화는 GitHub만큼 검색이 쉽지 않아, 대화 속에 묻히곤 합니다.
+
+## FastAPI Cloud 사용해보기 { #try-fastapi-cloud }
+
+FastAPI와 friends의 주요 자금은 단일 명령어 `fastapi deploy`로 FastAPI 애플리케이션을 간단하고 빠르게 배포할 수 있는 플랫폼인 [**FastAPI Cloud**](https://fastapicloud.com)에서 나옵니다.
+
+FastAPI Cloud는 FastAPI를 만든 같은 팀이 구축했습니다. 사용해보고 여러분의 프로젝트에 고려해볼 수 있습니다.
@@ -54,11 +54,11 @@

 ## 필요조건 { #requirements }

-여러 대안을 테스트한 후, 장점 때문에 [**Pydantic**](https://docs.pydantic.dev/)을 사용하기로 결정했습니다.
+여러 대안을 테스트한 후, 장점 때문에 [**Pydantic**](https://pydantic.dev/docs/)을 사용하기로 결정했습니다.

 그 후, JSON Schema를 완전히 준수하도록 하고, 제약 조건 선언을 정의하는 다양한 방식을 지원하며, 여러 편집기에서의 테스트를 바탕으로 편집기 지원(타입 검사, 자동 완성)을 개선하기 위해 기여했습니다.

-개발 과정에서, 또 다른 핵심 필요조건인 [**Starlette**](https://www.starlette.dev/)에도 기여했습니다.
+개발 과정에서, 또 다른 핵심 필요조건인 [**Starlette**](https://starlette.dev/)에도 기여했습니다.

 ## 개발 { #development }

@@ -110,7 +110,7 @@ FastAPI는 현대적이고, 빠르며(고성능), 파이썬 표준 타입 힌트
  </div>
  <div class="fastapi-opinions__panel" id="fo-panel-uber" role="tabpanel" aria-labelledby="fo-tab-uber" tabindex="0" hidden>
    <blockquote class="fastapi-opinions__quote">"우리는 <strong>FastAPI</strong> 라이브러리를 채택해 <strong>예측</strong>을 얻기 위해 쿼리할 수 있는 <strong>REST</strong> 서버를 생성했습니다." <em>[Ludwig을 위해]</em></blockquote>
-    <div class="fastapi-opinions__attr">— Piero Molino, Yaroslav Dudin, Sai Sumanth Miryala, <strong>Uber</strong> <a href="https://eng.uber.com/ludwig-v0-2/">(ref)</a></div>
+    <div class="fastapi-opinions__attr">— Piero Molino, Yaroslav Dudin, Sai Sumanth Miryala, <strong>Uber</strong> <a href="https://www.uber.com/us/en/blog/ludwig-v0-2/">(ref)</a></div>
  </div>
  <div class="fastapi-opinions__panel" id="fo-panel-netflix" role="tabpanel" aria-labelledby="fo-tab-netflix" tabindex="0" hidden>
    <blockquote class="fastapi-opinions__quote">"<strong>Netflix</strong>는 우리의 <strong>위기 관리</strong> 오케스트레이션 프레임워크인 <strong>Dispatch</strong>의 오픈 소스 공개를 발표하게 되어 기쁩니다!" <em>[FastAPI로 빌드]</em></blockquote>
@@ -133,7 +133,7 @@ FastAPI는 현대적이고, 빠르며(고성능), 파이썬 표준 타입 힌트

 "_**FastAPI** 라이브러리를 채택하여 **예측**을 얻기 위해 쿼리를 실행할 수 있는 **REST** 서버를 생성했습니다. [Ludwig을 위해]_"

-<div style="text-align: right; margin-right: 10%;">Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - <strong>Uber</strong> <a href="https://eng.uber.com/ludwig-v0-2/"><small>(ref)</small></a></div>
+<div style="text-align: right; margin-right: 10%;">Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - <strong>Uber</strong> <a href="https://www.uber.com/us/en/blog/ludwig-v0-2/"><small>(ref)</small></a></div>

 ---

@@ -175,17 +175,17 @@ FastAPI는 현대적이고, 빠르며(고성능), 파이썬 표준 타입 힌트

 FastAPI는 거인들의 어깨 위에 서 있습니다:

-* [Starlette](https://www.starlette.dev/) — 웹 부분을 담당합니다.
-* [Pydantic](https://docs.pydantic.dev/) — 데이터 부분을 담당합니다.
+* [Starlette](https://starlette.dev/) — 웹 부분을 담당합니다.
+* [Pydantic](https://pydantic.dev/docs/) — 데이터 부분을 담당합니다.

 ## 설치 { #installation }

-[가상 환경](https://fastapi.tiangolo.com/ko/virtual-environments/)을 생성하고 활성화한 다음 FastAPI를 설치하세요:
+먼저, [`uv`를 설치](https://docs.astral.sh/uv/getting-started/installation/)한 다음 FastAPI를 프로젝트에 추가하세요:

 <div class="termy">

 ```console
-$ pip install "fastapi[standard]"
+$ uv add "fastapi[standard]"

 ---> 100%
 ```
@@ -194,6 +194,8 @@ $ pip install "fastapi[standard]"

 **참고**: 모든 터미널에서 동작하도록 `"fastapi[standard]"`를 따옴표로 감싸 넣었는지 확인하세요.

+`pip` 사용을 선호한다면, 가상 환경 안에서 `fastapi[standard]`를 설치하세요. 대안 단계는 [설치 가이드](tutorial/#install-fastapi)를 보세요.
+
 ## 예제 { #example }

 ### 만들기 { #create-it }
@@ -250,7 +252,7 @@ async def read_item(item_id: int, q: str | None = None):
 <div class="termy">

 ```console
-$ fastapi dev
+$ uv run fastapi dev

 ╭────────── FastAPI CLI - Development mode ───────────╮
 │                                                     │
@@ -277,7 +279,7 @@ INFO:     Application startup complete.
 <details markdown="1">
 <summary><code>fastapi dev</code> 명령에 관하여...</summary>

-`fastapi dev` 명령은 여러분의 `main.py` 파일을 자동으로 읽고, 그 안의 **FastAPI** 앱을 감지한 다음, [Uvicorn](https://www.uvicorn.dev)을 사용해 서버를 시작합니다.
+`fastapi dev` 명령은 여러분의 `main.py` 파일을 자동으로 읽고, 그 안의 **FastAPI** 앱을 감지한 다음, [Uvicorn](https://uvicorn.dev)을 사용해 서버를 시작합니다.

 기본적으로 `fastapi dev`는 로컬 개발을 위해 auto-reload가 활성화된 상태로 시작됩니다.

@@ -314,7 +316,7 @@ INFO:     Application startup complete.

 그리고 이제 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)로 가봅시다.

-다른 자동 문서를 볼 수 있습니다([ReDoc](https://github.com/Rebilly/ReDoc) 제공):
+다른 자동 문서를 볼 수 있습니다([ReDoc](https://github.com/Redocly/redoc) 제공):

 ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png)

@@ -497,7 +499,7 @@ item: Item
 <div class="termy">

 ```console
-$ fastapi deploy
+$ uv run fastapi deploy

 Deploying to FastAPI Cloud...

@@ -540,7 +542,7 @@ FastAPI는 Pydantic과 Starlette에 의존합니다.

 ### `standard` 의존성 { #standard-dependencies }

-`pip install "fastapi[standard]"`로 FastAPI를 설치하면 `standard` 그룹의 선택적 의존성이 함께 설치됩니다.
+`uv add "fastapi[standard]"`로 FastAPI를 설치하면 `standard` 그룹의 선택적 의존성이 함께 설치됩니다:

 Pydantic이 사용하는:

@@ -554,17 +556,17 @@ Starlette이 사용하는:

 FastAPI가 사용하는:

-* [`uvicorn`](https://www.uvicorn.dev) - 애플리케이션을 로드하고 제공하는 서버를 위한 것입니다. 여기에는 고성능 서빙에 필요한 일부 의존성(예: `uvloop`)이 포함된 `uvicorn[standard]`가 포함됩니다.
+* [`uvicorn`](https://uvicorn.dev) - 애플리케이션을 로드하고 제공하는 서버를 위한 것입니다. 여기에는 고성능 서빙에 필요한 일부 의존성(예: `uvloop`)이 포함된 `uvicorn[standard]`가 포함됩니다.
 * `fastapi-cli[standard]` - `fastapi` 명령을 제공하기 위한 것입니다.
    * 여기에는 [FastAPI Cloud](https://fastapicloud.com)에 FastAPI 애플리케이션을 배포할 수 있게 해주는 `fastapi-cloud-cli`가 포함됩니다.

 ### `standard` 의존성 없이 { #without-standard-dependencies }

-`standard` 선택적 의존성을 포함하고 싶지 않다면, `pip install "fastapi[standard]"` 대신 `pip install fastapi`로 설치할 수 있습니다.
+`standard` 선택적 의존성을 포함하고 싶지 않다면, `uv add "fastapi[standard]"` 대신 `uv add fastapi`로 설치할 수 있습니다.

 ### `fastapi-cloud-cli` 없이 { #without-fastapi-cloud-cli }

-표준 의존성과 함께 FastAPI를 설치하되 `fastapi-cloud-cli` 없이 설치하고 싶다면, `pip install "fastapi[standard-no-fastapi-cloud-cli]"`로 설치할 수 있습니다.
+표준 의존성과 함께 FastAPI를 설치하되 `fastapi-cloud-cli` 없이 설치하고 싶다면, `uv add "fastapi[standard-no-fastapi-cloud-cli]"`로 설치할 수 있습니다.

 ### 추가 선택적 의존성 { #additional-optional-dependencies }

@@ -572,13 +574,13 @@ FastAPI가 사용하는:

 추가 선택적 Pydantic 의존성:

-* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - 설정 관리를 위한 것입니다.
-* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - Pydantic에서 사용할 추가 타입을 위한 것입니다.
+* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - 설정 관리를 위한 것입니다.
+* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - Pydantic에서 사용할 추가 타입을 위한 것입니다.

 추가 선택적 FastAPI 의존성:

 * [`orjson`](https://github.com/ijl/orjson) - `ORJSONResponse`를 사용하려면 필요.
-* [`ujson`](https://github.com/esnme/ultrajson) - `UJSONResponse`를 사용하려면 필요.
+* [`ujson`](https://github.com/ultrajson/ultrajson) - `UJSONResponse`를 사용하려면 필요.

 ## 라이센스 { #license }

@@ -5,13 +5,13 @@

 많은 초기 설정, 보안, 데이터베이스 및 일부 API 엔드포인트가 이미 준비되어 있으므로, 여러분은 이 템플릿을 시작하는 데 사용할 수 있습니다.

-GitHub 저장소: [Full Stack FastAPI 템플릿](https://github.com/tiangolo/full-stack-fastapi-template)
+GitHub 저장소: [Full Stack FastAPI 템플릿](https://github.com/fastapi/full-stack-fastapi-template)

 ## Full Stack FastAPI 템플릿 - 기술 스택과 기능들 { #full-stack-fastapi-template-technology-stack-and-features }

 - ⚡ Python 백엔드 API를 위한 [**FastAPI**](https://fastapi.tiangolo.com/ko).
    - 🧰 Python SQL 데이터베이스 상호작용을 위한 [SQLModel](https://sqlmodel.tiangolo.com) (ORM).
-    - 🔍 FastAPI에 의해 사용되는, 데이터 검증과 설정 관리를 위한 [Pydantic](https://docs.pydantic.dev).
+    - 🔍 FastAPI에 의해 사용되는, 데이터 검증과 설정 관리를 위한 [Pydantic](https://pydantic.dev/docs/).
    - 💾 SQL 데이터베이스로서의 [PostgreSQL](https://www.postgresql.org).
 - 🚀 프론트엔드를 위한 [React](https://react.dev).
    - 💃 TypeScript, hooks, Vite 및 기타 현대적인 프론트엔드 스택을 사용.
@@ -271,7 +271,7 @@ def some_function(data: Any):

 ## Pydantic 모델 { #pydantic-models }

-[Pydantic](https://docs.pydantic.dev/)은 데이터 검증을 수행하는 파이썬 라이브러리입니다.
+[Pydantic](https://pydantic.dev/docs/)은 데이터 검증을 수행하는 파이썬 라이브러리입니다.

 속성을 가진 클래스 형태로 데이터의 "모양(shape)"을 선언합니다.

@@ -287,7 +287,7 @@ Pydantic 공식 문서의 예시:

 /// note | 참고

-더 알아보려면 [Pydantic 문서를 확인하세요](https://docs.pydantic.dev/).
+더 알아보려면 [Pydantic 문서를 확인하세요](https://pydantic.dev/docs/).

 ///

@@ -1,865 +1,35 @@
 # 가상 환경 { #virtual-environments }

+Python 프로젝트를 작업할 때는 각 프로젝트에 설치된 패키지를 분리하기 위해 **가상 환경**을 사용해야 합니다.

-Python 프로젝트를 작업할 때는 **가상 환경**(또는 이와 유사한 메커니즘)을 사용해 각 프로젝트마다 설치하는 패키지를 분리하는 것이 좋습니다.
-
-/// note | 참고
-
-이미 가상 환경에 대해 알고 있고, 어떻게 생성하고 사용하는지도 알고 있다면, 이 섹션은 건너뛰어도 괜찮습니다. 🤓
-
-///
-
-/// tip | 팁
-
-**가상 환경**은 **환경 변수**와 다릅니다.
-
-**환경 변수**는 시스템에 존재하며, 프로그램이 사용할 수 있는 변수입니다.
-
-**가상 환경**은 몇몇 파일로 구성된 하나의 디렉터리입니다.
-
-///
-
-/// note | 참고
-
-이 페이지에서는 **가상 환경**을 사용하는 방법과 작동 방식을 알려드립니다.
-
-Python 설치까지 포함해 **모든 것을 관리해주는 도구**를 도입할 준비가 되었다면 [uv](https://github.com/astral-sh/uv)를 사용해 보세요.
-
-///
+FastAPI 프로젝트에서는 프로젝트, 의존성, 가상 환경을 관리하기 위해 [uv](https://docs.astral.sh/uv/)를 사용하는 것을 권장합니다.

 ## 프로젝트 생성 { #create-a-project }

-먼저, 프로젝트를 위한 디렉터리를 하나 생성합니다.
-
-제가 보통 하는 방법은 사용자 홈/유저 디렉터리 안에 `code`라는 디렉터리를 만드는 것입니다.
-
-그리고 그 안에 프로젝트마다 디렉터리를 하나씩 만듭니다.
+[공식 설치 가이드](https://docs.astral.sh/uv/getting-started/installation/)를 사용해 `uv`를 설치한 다음, 프로젝트를 생성하세요:

 <div class="termy">

 ```console
-// 홈 디렉터리로 이동
-$ cd
-// 모든 코드 프로젝트를 위한 디렉터리 생성
-$ mkdir code
-// 그 code 디렉터리로 이동
-$ cd code
-// 이 프로젝트를 위한 디렉터리 생성
-$ mkdir awesome-project
-// 그 프로젝트 디렉터리로 이동
+$ uv init awesome-project --bare
 $ cd awesome-project
+$ uv add "fastapi[standard]"
 ```

 </div>

-## 가상 환경 생성 { #create-a-virtual-environment }
+`uv`는 프로젝트를 위한 가상 환경을 자동으로 생성합니다. 직접 생성하거나 활성화할 필요가 없습니다.

-Python 프로젝트를 **처음 시작할 때**, 가상 환경을 **<dfn title="다른 옵션도 있지만, 이것은 간단한 가이드라인입니다">프로젝트 내부</dfn>**에 생성하세요.
-
-/// tip | 팁
-
-이 작업은 **프로젝트당 한 번만** 하면 되며, 작업할 때마다 할 필요는 없습니다.
-
-///
-
-//// tab | `venv`
-
-가상 환경을 만들려면 Python에 포함된 `venv` 모듈을 사용할 수 있습니다.
+예를 들어, 프로젝트 환경 안에서 `uv run`으로 명령어를 실행하세요:

 <div class="termy">

 ```console
-$ python -m venv .venv
+$ uv run fastapi dev
 ```

 </div>

-/// details | 명령어 의미
+## 더 알아보기 { #learn-more }

-* `python`: `python`이라는 프로그램을 사용합니다
-* `-m`: 모듈을 스크립트로 호출합니다. 다음에 어떤 모듈인지 지정합니다
-* `venv`: 보통 Python에 기본으로 설치되어 있는 `venv` 모듈을 사용합니다
-* `.venv`: 새 디렉터리인 `.venv`에 가상 환경을 생성합니다
-
-///
-
-////
-
-//// tab | `uv`
-
-[`uv`](https://github.com/astral-sh/uv)가 설치되어 있다면, 이를 사용해 가상 환경을 생성할 수 있습니다.
-
-<div class="termy">
-
-```console
-$ uv venv
-```
-
-</div>
-
-/// tip | 팁
-
-기본적으로 `uv`는 `.venv`라는 디렉터리에 가상 환경을 생성합니다.
-
-하지만 디렉터리 이름을 추가 인자로 전달해 이를 커스터마이즈할 수 있습니다.
-
-///
-
-////
-
-해당 명령어는 `.venv`라는 디렉터리에 새로운 가상 환경을 생성합니다.
-
-/// details | `.venv` 또는 다른 이름
-
-가상 환경을 다른 디렉터리에 생성할 수도 있지만, 관례적으로 `.venv`라는 이름을 사용합니다.
-
-///
-
-## 가상 환경 활성화 { #activate-the-virtual-environment }
-
-이후 실행하는 Python 명령어와 설치하는 패키지가 새 가상 환경을 사용하도록, 새 가상 환경을 활성화하세요.
-
-/// tip | 팁
-
-프로젝트 작업을 위해 **새 터미널 세션**을 시작할 때마다 **매번** 이 작업을 하세요.
-
-///
-
-//// tab | Linux, macOS
-
-<div class="termy">
-
-```console
-$ source .venv/bin/activate
-```
-
-</div>
-
-////
-
-//// tab | Windows PowerShell
-
-<div class="termy">
-
-```console
-$ .venv\Scripts\Activate.ps1
-```
-
-</div>
-
-////
-
-//// tab | Windows Bash
-
-또는 Windows에서 Bash(예: [Git Bash](https://gitforwindows.org/))를 사용하는 경우:
-
-<div class="termy">
-
-```console
-$ source .venv/Scripts/activate
-```
-
-</div>
-
-////
-
-/// tip | 팁
-
-해당 환경에 **새 패키지**를 설치할 때마다, 환경을 다시 **활성화**하세요.
-
-이렇게 하면 해당 패키지가 설치한 **터미널(<abbr title="command line interface - 명령줄 인터페이스">CLI</abbr>) 프로그램**을 사용할 때, 전역으로 설치되어 있을 수도 있는(아마 필요한 버전과는 다른 버전인) 다른 프로그램이 아니라 가상 환경에 있는 것을 사용하게 됩니다.
-
-///
-
-## 가상 환경 활성화 여부 확인 { #check-the-virtual-environment-is-active }
-
-가상 환경이 활성화되어 있는지(이전 명령어가 작동했는지) 확인합니다.
-
-/// tip | 팁
-
-이 단계는 **선택 사항**이지만, 모든 것이 예상대로 작동하고 있는지, 그리고 의도한 가상 환경을 사용하고 있는지 **확인**하는 좋은 방법입니다.
-
-///
-
-//// tab | Linux, macOS, Windows Bash
-
-<div class="termy">
-
-```console
-$ which python
-
-/home/user/code/awesome-project/.venv/bin/python
-```
-
-</div>
-
-프로젝트 내부(이 경우 `awesome-project`)의 `.venv/bin/python`에 있는 `python` 바이너리가 표시된다면, 정상적으로 작동한 것입니다. 🎉
-
-////
-
-//// tab | Windows PowerShell
-
-<div class="termy">
-
-```console
-$ Get-Command python
-
-C:\Users\user\code\awesome-project\.venv\Scripts\python
-```
-
-</div>
-
-프로젝트 내부(이 경우 `awesome-project`)의 `.venv\Scripts\python`에 있는 `python` 바이너리가 표시된다면, 정상적으로 작동한 것입니다. 🎉
-
-////
-
-## `pip` 업그레이드 { #upgrade-pip }
-
-/// tip | 팁
-
-[`uv`](https://github.com/astral-sh/uv)를 사용한다면, `pip` 대신 `uv`로 설치하게 되므로 `pip`을 업그레이드할 필요가 없습니다. 😎
-
-///
-
-`pip`로 패키지를 설치한다면(Python에 기본으로 포함되어 있습니다) 최신 버전으로 **업그레이드**하는 것이 좋습니다.
-
-패키지 설치 중 발생하는 다양한 특이한 오류는 먼저 `pip`를 업그레이드하는 것만으로 해결되는 경우가 많습니다.
-
-/// tip | 팁
-
-보통 이 작업은 가상 환경을 만든 직후 **한 번만** 하면 됩니다.
-
-///
-
-가상 환경이 활성화된 상태인지 확인한 다음(위의 명령어 사용) 아래를 실행하세요:
-
-<div class="termy">
-
-```console
-$ python -m pip install --upgrade pip
-
---> 100%
-```
-
-</div>
-
-/// tip | 팁
-
-때로는 pip를 업그레이드하려고 할 때 **`No module named pip`** 오류가 발생할 수 있습니다.
-
-이 경우 아래 명령어로 pip를 설치하고 업그레이드하세요:
-
-<div class="termy">
-
-```console
-$ python -m ensurepip --upgrade
-
---> 100%
-```
-
-</div>
-
-이 명령어는 pip가 아직 설치되어 있지 않다면 설치하며, 설치된 pip 버전이 `ensurepip`에서 제공 가능한 버전만큼 최신임을 보장합니다.
-
-///
-
-## `.gitignore` 추가하기 { #add-gitignore }
-
-**Git**을 사용하고 있다면(사용하는 것이 좋습니다), `.venv`의 모든 내용을 Git에서 제외하도록 `.gitignore` 파일을 추가하세요.
-
-/// tip | 팁
-
-[`uv`](https://github.com/astral-sh/uv)로 가상 환경을 만들었다면, 이미 자동으로 처리되어 있으므로 이 단계는 건너뛰어도 됩니다. 😎
-
-///
-
-/// tip | 팁
-
-가상 환경을 만든 직후 **한 번만** 하면 됩니다.
-
-///
-
-<div class="termy">
-
-```console
-$ echo "*" > .venv/.gitignore
-```
-
-</div>
-
-/// details | 명령어 의미
-
-* `echo "*"`: 터미널에 `*` 텍스트를 "출력"합니다(다음 부분이 이를 약간 변경합니다)
-* `>`: `>` 왼쪽 명령어가 터미널에 출력한 내용을 터미널에 출력하지 않고, `>` 오른쪽에 있는 파일에 기록하라는 의미입니다
-* `.gitignore`: 텍스트가 기록될 파일 이름입니다
-
-그리고 Git에서 `*`는 "모든 것"을 의미합니다. 따라서 `.venv` 디렉터리 안의 모든 것을 무시합니다.
-
-이 명령어는 다음 내용을 가진 `.gitignore` 파일을 생성합니다:
-
-```gitignore
-*
-```
-
-///
-
-## 패키지 설치 { #install-packages }
-
-환경을 활성화한 뒤, 그 안에 패키지를 설치할 수 있습니다.
-
-/// tip | 팁
-
-프로젝트에 필요한 패키지를 설치하거나 업그레이드할 때는 **한 번**만 하면 됩니다.
-
-버전을 업그레이드하거나 새 패키지를 추가해야 한다면 **다시 이 작업을** 하게 됩니다.
-
-///
-
-### 패키지 직접 설치 { #install-packages-directly }
-
-급하게 작업 중이고 프로젝트의 패키지 요구사항을 선언하는 파일을 사용하고 싶지 않다면, 패키지를 직접 설치할 수 있습니다.
-
-/// tip | 팁
-
-프로그램에 필요한 패키지와 버전을 파일(예: `requirements.txt` 또는 `pyproject.toml`)에 적어두는 것은 (매우) 좋은 생각입니다.
-
-///
-
-//// tab | `pip`
-
-<div class="termy">
-
-```console
-$ pip install "fastapi[standard]"
-
---> 100%
-```
-
-</div>
-
-////
-
-//// tab | `uv`
-
-[`uv`](https://github.com/astral-sh/uv)가 있다면:
-
-<div class="termy">
-
-```console
-$ uv pip install "fastapi[standard]"
---> 100%
-```
-
-</div>
-
-////
-
-### `requirements.txt`에서 설치 { #install-from-requirements-txt }
-
-`requirements.txt`가 있다면, 이제 이를 사용해 그 안의 패키지를 설치할 수 있습니다.
-
-//// tab | `pip`
-
-<div class="termy">
-
-```console
-$ pip install -r requirements.txt
---> 100%
-```
-
-</div>
-
-////
-
-//// tab | `uv`
-
-[`uv`](https://github.com/astral-sh/uv)가 있다면:
-
-<div class="termy">
-
-```console
-$ uv pip install -r requirements.txt
---> 100%
-```
-
-</div>
-
-////
-
-/// details | `requirements.txt`
-
-일부 패키지가 있는 `requirements.txt`는 다음과 같이 생겼을 수 있습니다:
-
-```requirements.txt
-fastapi[standard]==0.113.0
-pydantic==2.8.0
-```
-
-///
-
-## 프로그램 실행 { #run-your-program }
-
-가상 환경을 활성화한 뒤에는 프로그램을 실행할 수 있으며, 설치한 패키지가 들어있는 가상 환경 내부의 Python을 사용하게 됩니다.
-
-<div class="termy">
-
-```console
-$ python main.py
-
-Hello World
-```
-
-</div>
-
-## 에디터 설정 { #configure-your-editor }
-
-아마 에디터를 사용할 텐데, 자동 완성과 인라인 오류 표시를 받을 수 있도록 생성한 가상 환경을 사용하도록 설정하세요(대부분 자동 감지합니다).
-
-예를 들면:
-
-* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment)
-* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html)
-
-/// tip | 팁
-
-보통 이 설정은 가상 환경을 만들 때 **한 번만** 하면 됩니다.
-
-///
-
-## 가상 환경 비활성화 { #deactivate-the-virtual-environment }
-
-프로젝트 작업을 마쳤다면 가상 환경을 **비활성화**할 수 있습니다.
-
-<div class="termy">
-
-```console
-$ deactivate
-```
-
-</div>
-
-이렇게 하면 `python`을 실행할 때, 해당 가상 환경과 그 안에 설치된 패키지에서 실행하려고 하지 않습니다.
-
-## 작업할 준비 완료 { #ready-to-work }
-
-이제 프로젝트 작업을 시작할 준비가 되었습니다.
-
-
-
-/// tip | 팁
-
-위의 내용이 무엇인지 더 이해하고 싶으신가요?
-
-계속 읽어보세요. 👇🤓
-
-///
-
-## 가상 환경을 왜 사용하나요 { #why-virtual-environments }
-
-FastAPI로 작업하려면 [Python](https://www.python.org/)을 설치해야 합니다.
-
-그 다음 FastAPI와 사용하려는 다른 **패키지**를 **설치**해야 합니다.
-
-패키지를 설치할 때는 보통 Python에 포함된 `pip` 명령어(또는 유사한 대안)를 사용합니다.
-
-하지만 `pip`를 그대로 직접 사용하면, 패키지는 **전역 Python 환경**(전역 Python 설치)에 설치됩니다.
-
-### 문제점 { #the-problem }
-
-그렇다면, 전역 Python 환경에 패키지를 설치하면 어떤 문제가 있을까요?
-
-어느 시점이 되면 **서로 다른 패키지**에 의존하는 다양한 프로그램을 작성하게 될 것입니다. 그리고 작업하는 프로젝트 중 일부는 같은 패키지의 **서로 다른 버전**에 의존할 수도 있습니다. 😱
-
-예를 들어 `philosophers-stone`이라는 프로젝트를 만들 수 있습니다. 이 프로그램은 **`harry`라는 다른 패키지의 버전 `1`**에 의존합니다. 그래서 `harry`를 설치해야 합니다.
-
-```mermaid
-flowchart LR
-    stone(philosophers-stone) -->|requires| harry-1[harry v1]
-```
-
-그다음, 나중에 `prisoner-of-azkaban`이라는 또 다른 프로젝트를 만들고, 이 프로젝트도 `harry`에 의존하지만, 이 프로젝트는 **`harry` 버전 `3`**이 필요합니다.
-
-```mermaid
-flowchart LR
-    azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3]
-```
-
-하지만 이제 문제가 생깁니다. 로컬 **가상 환경**이 아니라 전역(전역 환경)에 패키지를 설치한다면, 어떤 버전의 `harry`를 설치할지 선택해야 합니다.
-
-`philosophers-stone`을 실행하고 싶다면, 먼저 `harry` 버전 `1`을 다음과 같이 설치해야 합니다:
-
-<div class="termy">
-
-```console
-$ pip install "harry==1"
-```
-
-</div>
-
-그리고 전역 Python 환경에 `harry` 버전 `1`이 설치된 상태가 됩니다.
-
-```mermaid
-flowchart LR
-    subgraph global[global env]
-        harry-1[harry v1]
-    end
-    subgraph stone-project[philosophers-stone project]
-        stone(philosophers-stone) -->|requires| harry-1
-    end
-```
-
-하지만 `prisoner-of-azkaban`을 실행하려면 `harry` 버전 `1`을 제거하고 `harry` 버전 `3`을 설치해야 합니다(또는 버전 `3`을 설치하기만 해도 버전 `1`이 자동으로 제거됩니다).
-
-<div class="termy">
-
-```console
-$ pip install "harry==3"
-```
-
-</div>
-
-그러면 전역 Python 환경에 `harry` 버전 `3`이 설치된 상태가 됩니다.
-
-그리고 `philosophers-stone`을 다시 실행하려고 하면, `harry` 버전 `1`이 필요하기 때문에 **작동하지 않을** 가능성이 있습니다.
-
-```mermaid
-flowchart LR
-    subgraph global[global env]
-        harry-1[<strike>harry v1</strike>]
-        style harry-1 fill:#ccc,stroke-dasharray: 5 5
-        harry-3[harry v3]
-    end
-    subgraph stone-project[philosophers-stone project]
-        stone(philosophers-stone) -.-x|⛔️| harry-1
-    end
-    subgraph azkaban-project[prisoner-of-azkaban project]
-        azkaban(prisoner-of-azkaban) --> |requires| harry-3
-    end
-```
-
-/// tip | 팁
-
-Python 패키지에서는 **새 버전**에서 **호환성을 깨뜨리는 변경(breaking changes)**을 **피하려고** 최선을 다하는 것이 매우 일반적이지만, 안전을 위해 더 최신 버전은 의도적으로 설치하고, 테스트를 실행해 모든 것이 올바르게 작동하는지 확인할 수 있을 때 설치하는 것이 좋습니다.
-
-///
-
-이제 이런 일이 여러분의 **모든 프로젝트가 의존하는** **많은** 다른 **패키지**에서도 일어난다고 상상해 보세요. 이는 관리하기가 매우 어렵습니다. 그리고 결국 일부 프로젝트는 패키지의 **호환되지 않는 버전**으로 실행하게 될 가능성이 높으며, 왜 무언가가 작동하지 않는지 알지 못하게 될 수 있습니다.
-
-또한 운영체제(Linux, Windows, macOS 등)에 따라 Python이 이미 설치되어 있을 수도 있습니다. 그런 경우에는 시스템에 **필요한 특정 버전**의 패키지가 일부 미리 설치되어 있을 가능성이 큽니다. 전역 Python 환경에 패키지를 설치하면, 운영체제에 포함된 프로그램 일부가 **깨질** 수 있습니다.
-
-## 패키지는 어디에 설치되나요 { #where-are-packages-installed }
-
-Python을 설치하면 컴퓨터에 몇몇 파일이 들어 있는 디렉터리가 생성됩니다.
-
-이 디렉터리 중 일부는 설치한 모든 패키지를 담는 역할을 합니다.
-
-다음을 실행하면:
-
-<div class="termy">
-
-```console
-// 지금은 실행하지 마세요, 예시일 뿐입니다 🤓
-$ pip install "fastapi[standard]"
---> 100%
-```
-
-</div>
-
-FastAPI 코드를 담은 압축 파일을 다운로드합니다. 보통 [PyPI](https://pypi.org/project/fastapi/)에서 받습니다.
-
-또한 FastAPI가 의존하는 다른 패키지들의 파일도 **다운로드**합니다.
-
-그 다음 모든 파일을 **압축 해제**하고 컴퓨터의 한 디렉터리에 넣습니다.
-
-기본적으로, 다운로드하고 압축 해제한 파일들은 Python 설치와 함께 제공되는 디렉터리, 즉 **전역 환경**에 저장됩니다.
-
-## 가상 환경이란 무엇인가요 { #what-are-virtual-environments }
-
-전역 환경에 모든 패키지를 두는 문제에 대한 해결책은 작업하는 **각 프로젝트마다 가상 환경**을 사용하는 것입니다.
-
-가상 환경은 전역 환경과 매우 유사한 하나의 **디렉터리**이며, 프로젝트의 패키지를 설치할 수 있습니다.
-
-이렇게 하면 각 프로젝트는 자체 가상 환경(`.venv` 디렉터리)과 자체 패키지를 갖게 됩니다.
-
-```mermaid
-flowchart TB
-    subgraph stone-project[philosophers-stone project]
-        stone(philosophers-stone) --->|requires| harry-1
-        subgraph venv1[.venv]
-            harry-1[harry v1]
-        end
-    end
-    subgraph azkaban-project[prisoner-of-azkaban project]
-        azkaban(prisoner-of-azkaban) --->|requires| harry-3
-        subgraph venv2[.venv]
-            harry-3[harry v3]
-        end
-    end
-    stone-project ~~~ azkaban-project
-```
-
-## 가상 환경을 활성화한다는 것은 무엇을 의미하나요 { #what-does-activating-a-virtual-environment-mean }
-
-가상 환경을 활성화한다는 것은, 예를 들어 다음과 같은 명령어로:
-
-//// tab | Linux, macOS
-
-<div class="termy">
-
-```console
-$ source .venv/bin/activate
-```
-
-</div>
-
-////
-
-//// tab | Windows PowerShell
-
-<div class="termy">
-
-```console
-$ .venv\Scripts\Activate.ps1
-```
-
-</div>
-
-////
-
-//// tab | Windows Bash
-
-또는 Windows에서 Bash(예: [Git Bash](https://gitforwindows.org/))를 사용하는 경우:
-
-<div class="termy">
-
-```console
-$ source .venv/Scripts/activate
-```
-
-</div>
-
-////
-
-다음 명령어들에서 사용할 수 있는 몇몇 [환경 변수](environment-variables.md)를 생성하거나 수정하는 것을 의미합니다.
-
-그 변수 중 하나가 `PATH` 변수입니다.
-
-/// tip | 팁
-
-`PATH` 환경 변수에 대해 더 알아보려면 [환경 변수](environment-variables.md#path-environment-variable) 섹션을 참고하세요.
-
-///
-
-가상 환경을 활성화하면 가상 환경의 경로인 `.venv/bin`(Linux와 macOS) 또는 `.venv\Scripts`(Windows)를 `PATH` 환경 변수에 추가합니다.
-
-가령 환경을 활성화하기 전에는 `PATH` 변수가 다음과 같았다고 해보겠습니다:
-
-//// tab | Linux, macOS
-
-```plaintext
-/usr/bin:/bin:/usr/sbin:/sbin
-```
-
-이는 시스템이 다음 위치에서 프로그램을 찾는다는 뜻입니다:
-
-* `/usr/bin`
-* `/bin`
-* `/usr/sbin`
-* `/sbin`
-
-////
-
-//// tab | Windows
-
-```plaintext
-C:\Windows\System32
-```
-
-이는 시스템이 다음 위치에서 프로그램을 찾는다는 뜻입니다:
-
-* `C:\Windows\System32`
-
-////
-
-가상 환경을 활성화한 뒤에는 `PATH` 변수가 다음과 같이 보일 수 있습니다:
-
-//// tab | Linux, macOS
-
-```plaintext
-/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin
-```
-
-이는 시스템이 이제 다음 위치에서 프로그램을 가장 먼저 찾기 시작한다는 뜻입니다:
-
-```plaintext
-/home/user/code/awesome-project/.venv/bin
-```
-
-그리고 나서 다른 디렉터리들을 탐색합니다.
-
-따라서 터미널에 `python`을 입력하면, 시스템은 다음 위치에서 Python 프로그램을 찾고:
-
-```plaintext
-/home/user/code/awesome-project/.venv/bin/python
-```
-
-그것을 사용하게 됩니다.
-
-////
-
-//// tab | Windows
-
-```plaintext
-C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32
-```
-
-이는 시스템이 이제 다음 위치에서 프로그램을 가장 먼저 찾기 시작한다는 뜻입니다:
-
-```plaintext
-C:\Users\user\code\awesome-project\.venv\Scripts
-```
-
-그리고 나서 다른 디렉터리들을 탐색합니다.
-
-따라서 터미널에 `python`을 입력하면, 시스템은 다음 위치에서 Python 프로그램을 찾고:
-
-```plaintext
-C:\Users\user\code\awesome-project\.venv\Scripts\python
-```
-
-그것을 사용하게 됩니다.
-
-////
-
-중요한 세부 사항은 가상 환경 경로가 `PATH` 변수의 **맨 앞**에 들어간다는 점입니다. 시스템은 다른 어떤 Python보다도 **먼저** 이를 찾게 됩니다. 이렇게 하면 `python`을 실행할 때, 다른 어떤 `python`(예: 전역 환경의 `python`)이 아니라 **가상 환경의 Python**을 사용하게 됩니다.
-
-가상 환경을 활성화하면 다른 몇 가지도 변경되지만, 이것이 그중 가장 중요한 것 중 하나입니다.
-
-## 가상 환경 확인하기 { #checking-a-virtual-environment }
-
-가상 환경이 활성화되어 있는지 확인할 때는, 예를 들어 다음을 사용합니다:
-
-//// tab | Linux, macOS, Windows Bash
-
-<div class="termy">
-
-```console
-$ which python
-
-/home/user/code/awesome-project/.venv/bin/python
-```
-
-</div>
-
-////
-
-//// tab | Windows PowerShell
-
-<div class="termy">
-
-```console
-$ Get-Command python
-
-C:\Users\user\code\awesome-project\.venv\Scripts\python
-```
-
-</div>
-
-////
-
-이는 사용될 `python` 프로그램이 **가상 환경 내부에 있는 것**이라는 뜻입니다.
-
-Linux와 macOS에서는 `which`, Windows PowerShell에서는 `Get-Command`를 사용합니다.
-
-이 명령어는 `PATH` 환경 변수에 있는 경로를 **순서대로** 확인하면서 `python`이라는 프로그램을 찾습니다. 찾는 즉시, 그 프로그램의 **경로를 보여줍니다**.
-
-가장 중요한 부분은 `python`을 호출했을 때, 실행될 정확한 "`python`"이 무엇인지 알 수 있다는 점입니다.
-
-따라서 올바른 가상 환경에 있는지 확인할 수 있습니다.
-
-/// tip | 팁
-
-가상 환경을 하나 활성화해서 Python을 사용한 다음, **다른 프로젝트로 이동**하기 쉽습니다.
-
-그리고 두 번째 프로젝트는 다른 프로젝트의 가상 환경에서 온 **잘못된 Python**을 사용하고 있기 때문에 **작동하지 않을** 수 있습니다.
-
-어떤 `python`이 사용되고 있는지 확인할 수 있으면 유용합니다. 🤓
-
-///
-
-## 가상 환경을 왜 비활성화하나요 { #why-deactivate-a-virtual-environment }
-
-예를 들어 `philosophers-stone` 프로젝트에서 작업하면서, **그 가상 환경을 활성화**하고, 패키지를 설치하고, 그 환경으로 작업하고 있다고 해보겠습니다.
-
-그런데 이제 **다른 프로젝트**인 `prisoner-of-azkaban`에서 작업하고 싶습니다.
-
-해당 프로젝트로 이동합니다:
-
-<div class="termy">
-
-```console
-$ cd ~/code/prisoner-of-azkaban
-```
-
-</div>
-
-`philosophers-stone`의 가상 환경을 비활성화하지 않으면, 터미널에서 `python`을 실행할 때 `philosophers-stone`의 Python을 사용하려고 할 것입니다.
-
-<div class="termy">
-
-```console
-$ cd ~/code/prisoner-of-azkaban
-
-$ python main.py
-
-// sirius 임포트 오류, 설치되어 있지 않습니다 😱
-Traceback (most recent call last):
-    File "main.py", line 1, in <module>
-        import sirius
-```
-
-</div>
-
-하지만 가상 환경을 비활성화하고 `prisoner-of-azkaban`에 대한 새 가상 환경을 활성화하면, `python`을 실행할 때 `prisoner-of-azkaban`의 가상 환경에 있는 Python을 사용하게 됩니다.
-
-<div class="termy">
-
-```console
-$ cd ~/code/prisoner-of-azkaban
-
-// 비활성화를 위해 이전 디렉터리에 있을 필요는 없습니다. 어디서든, 다른 프로젝트로 이동한 뒤에도 할 수 있습니다 😎
-$ deactivate
-
-// prisoner-of-azkaban/.venv의 가상 환경을 활성화하세요 🚀
-$ source .venv/bin/activate
-
-// 이제 python을 실행하면, 이 가상 환경에 설치된 sirius 패키지를 찾습니다 ✨
-$ python main.py
-
-I solemnly swear 🐺
-```
-
-</div>
-
-## 대안들 { #alternatives }
-
-이 문서는 시작을 돕고, 내부에서 모든 것이 어떻게 작동하는지 알려주는 간단한 가이드입니다.
-
-가상 환경, 패키지 의존성(requirements), 프로젝트를 관리하는 방법에는 많은 **대안**이 있습니다.
-
-준비가 되었고 **프로젝트 전체**, 패키지 의존성, 가상 환경 등을 **관리**하는 도구를 사용하고 싶다면 [uv](https://github.com/astral-sh/uv)를 사용해 보시길 권합니다.
-
-`uv`는 많은 일을 할 수 있습니다. 예를 들어:
-
-* 여러 버전을 포함해 **Python을 설치**
-* 프로젝트의 **가상 환경** 관리
-* **패키지** 설치
-* 프로젝트의 패키지 **의존성과 버전** 관리
-* 의존성을 포함해 설치할 패키지와 버전의 **정확한** 세트를 보장하여, 개발 중인 컴퓨터와 동일하게 프로덕션에서 실행할 수 있도록 합니다. 이를 **locking**이라고 합니다
-* 그 외에도 많은 기능이 있습니다
-
-## 결론 { #conclusion }
-
-여기까지 모두 읽고 이해했다면, 이제 많은 개발자들보다 가상 환경에 대해 **훨씬 더 많이** 알게 된 것입니다. 🤓
-
-이 세부 사항을 알고 있으면, 나중에 복잡해 보이는 무언가를 디버깅할 때 아마도 도움이 될 것입니다. **내부에서 어떻게 작동하는지** 알고 있기 때문입니다. 😎
+가상 환경이 내부적으로 어떻게 작동하는지, 활성화와 대안인 `python -m venv` 및 `pip` 워크플로를 포함해 알아보려면 [가상 환경 가이드](https://tiangolo.com/guides/virtual-environments/)를 읽어보세요.