Ubuntu 26.04에서 uv로 Python 설치하는 방법 (최신 버전·버전 변경)

Ubuntu 26.04 서버에 uv로 최신 Python을 설치하고, 여러 버전 설치와 프로젝트별 버전 변경, 가상환경과 패키지 설치, uv 명령을 찾을 수 없는 오류와 ModuleNotFoundError 해결, 깨끗하게 삭제하는 방법까지 정리합니다.

1. 준비물

• Ubuntu 26.04 LTS 서버 또는 PC 1대
• sudo 권한이 있는 일반 사용자 계정
• 인터넷 연결 (GitHub와 PyPI에서 파일을 내려받습니다)

서버가 없다면 DigitalOcean에서 Droplet을 생성해 보세요. 이 문서의 모든 과정은 Droplet(2 vCPU · 2GB 메모리 · 60GB SSD · Ubuntu 26.04 · 싱가포르)으로 서버를 생성하고, sudo 권한이 있는 일반 사용자 계정으로 확인했습니다.

2. 설치 전 상태 확인

Ubuntu 26.04에는 Python 3.14가 기본으로 들어 있습니다. 시스템 프로그램이 쓰는 Python이라 지우거나 다른 버전으로 바꾸면 안 됩니다.

python3 --version

Python 3.14.4

python 명령은 없습니다. Ubuntu는 python3라는 이름으로만 Python을 제공합니다.

python --version

Command 'python' not found, did you mean:
  command 'python3' from deb python3
  command 'python' from deb python-is-python3

패키지를 설치하는 pip3도 없고, 가상환경을 만드는 venv도 바로 쓸 수 없습니다.

pip3 --version

Command 'pip3' not found, but can be installed with:
sudo apt install python3-pip

python3 -m venv myenv

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.14-venv

You may need to use sudo with that command.  After installing the python3-venv
package, recreate your virtual environment.

Failing command: /home/devuser/myenv/bin/python3

실패하면서 만들다 만 myenv 폴더가 남으므로 지웁니다. 출력은 없습니다.

rm -rf myenv

Python 3.14는 2030년 10월까지 지원되는 버전이고, 이 문서를 확인한 날의 최신 Python은 3.15입니다. 이 문서는 시스템 Python은 그대로 두고 uv로 최신 Python을 사용자 폴더에 따로 설치합니다. uv는 Python 설치, 버전 변경, 가상환경, 패키지 설치를 한 프로그램으로 처리하는 도구이며, 미리 빌드된 Python을 내려받기 때문에 설치가 1분 안에 끝나고 sudo도 필요 없습니다.

3. uv 설치

uv 설치 스크립트를 내려받아 실행합니다. curl -LsSf는 진행 표시 없이 내려받고, 실패하면 오류를 표시한다는 뜻입니다. 내려받은 스크립트는 | sh로 넘겨 바로 실행합니다. 이 문서는 확인한 날의 최신 버전인 uv 0.13.1을 설치했습니다.

curl -LsSf https://astral.sh/uv/install.sh | sh

downloading uv 0.13.1 x86_64-unknown-linux-gnu
installing to /home/devuser/.local/bin
  uv
  uvx
everything's installed!

To add $HOME/.local/bin to your PATH, either restart your shell or run:

    source $HOME/.local/bin/env (sh, bash, zsh)
    source $HOME/.local/bin/env.fish (fish)

uv는 ~/.local/bin 폴더에 설치되고, 이 폴더를 명령 경로(PATH)에 추가하는 줄이 ~/.bashrc와 ~/.profile 끝에 추가됩니다.

4. uv 설치 확인

설치한 터미널에서 바로 uv를 실행하면 명령을 찾을 수 없다는 메시지가 표시됩니다. 이 터미널은 PATH가 추가되기 전에 열렸기 때문입니다.

uv --version

uv: command not found

설치 메시지의 안내대로 아래 명령을 실행하거나, 터미널을 닫고 새로 열면(SSH라면 접속을 끊고 다시 접속) 됩니다. 출력은 없습니다.

source $HOME/.local/bin/env

uv --version

uv 0.13.1 (x86_64-unknown-linux-gnu)

5. Python 최신 버전 설치

버전을 적지 않으면 가장 최신 Python을 설치합니다.

uv python install

Installed Python 3.15.0 in 2.79s
 + cpython-3.15.0-linux-x86_64-gnu (python3.15)

설치된 Python 목록을 확인합니다. uv가 설치한 Python과 시스템 Python(/usr/bin)이 함께 표시됩니다.

uv python list --only-installed

cpython-3.15.0-linux-x86_64-gnu    .local/bin/python3.15 -> .local/share/uv/python/cpython-3.15-linux-x86_64-gnu/bin/python3.15
cpython-3.15.0-linux-x86_64-gnu    .local/share/uv/python/cpython-3.15-linux-x86_64-gnu/bin/python3.15
cpython-3.14.4-linux-x86_64-gnu    /usr/bin/python3.14
cpython-3.14.4-linux-x86_64-gnu    /usr/bin/python3 -> python3.14

uv는 설치한 Python을 python3.15처럼 버전이 붙은 이름으로만 등록합니다. 그래서 python3.15는 실행되지만 python은 여전히 찾을 수 없습니다.

python3.15 --version

Python 3.15.0

python --version

Command 'python' not found, did you mean:
  command 'python3' from deb python3
  command 'python' from deb python-is-python3

python과 python3로도 Python 3.15를 실행하려면 --default를 붙여 다시 설치합니다. 이미 내려받은 Python이라 이름만 추가됩니다. 이 옵션은 아직 시험 기능이라 경고가 함께 표시되지만, 설치에는 문제가 없습니다.

uv python install 3.15 --default

warning: The `--default` option is experimental and may change without warning. Pass `--preview-features python-install-default` to disable this warning
Installed Python 3.15.0 in 86ms
 + cpython-3.15.0-linux-x86_64-gnu (python, python3)

python --version

Python 3.15.0

python3 --version

Python 3.15.0

which python

/home/devuser/.local/bin/python

6. 다른 버전 설치

다른 버전이 필요하면 버전 번호를 적어 설치합니다. 3.13처럼 적으면 3.13 계열의 최신 버전이 설치됩니다.

uv python install 3.13

Installed Python 3.13.16 in 2.25s
 + cpython-3.13.16-linux-x86_64-gnu (python3.13)

uv python list --only-installed

cpython-3.15.0-linux-x86_64-gnu     .local/bin/python3.15 -> .local/share/uv/python/cpython-3.15-linux-x86_64-gnu/bin/python3.15
cpython-3.15.0-linux-x86_64-gnu     .local/bin/python3 -> .local/share/uv/python/cpython-3.15-linux-x86_64-gnu/bin/python3.15
cpython-3.15.0-linux-x86_64-gnu     .local/bin/python -> .local/share/uv/python/cpython-3.15-linux-x86_64-gnu/bin/python3.15
cpython-3.15.0-linux-x86_64-gnu     .local/share/uv/python/cpython-3.15-linux-x86_64-gnu/bin/python3.15
cpython-3.14.4-linux-x86_64-gnu     /usr/bin/python3.14
cpython-3.14.4-linux-x86_64-gnu     /usr/bin/python3 -> python3.14
cpython-3.13.16-linux-x86_64-gnu    .local/bin/python3.13 -> .local/share/uv/python/cpython-3.13-linux-x86_64-gnu/bin/python3.13
cpython-3.13.16-linux-x86_64-gnu    .local/share/uv/python/cpython-3.13-linux-x86_64-gnu/bin/python3.13

Python 3.13은 python3.13으로 실행할 수 있고, python은 그대로 3.15입니다. 프로젝트마다 다른 버전을 쓰는 방법은 8단계에서 설명합니다.

7. 첫 프로젝트 만들고 패키지 설치

uv는 프로젝트 폴더마다 가상환경(.venv)을 만들어 패키지를 따로 관리합니다. 새 터미널을 열고 hello-python 프로젝트를 만듭니다. --no-package는 배포용 패키지 구조 없이 main.py 하나로 시작한다는 뜻입니다.

uv init --no-package hello-python

Initialized project `hello-python` at `/home/devuser/hello-python`

cd hello-python

ls -a

.  ..  .git  .gitignore  .python-version  README.md  main.py  pyproject.toml

.python-version은 이 프로젝트에서 쓸 Python 버전이 적힌 파일입니다. 기본으로 설치된 Python 중 가장 최신 버전인 3.15가 적혀 있습니다. main.py에는 인사말을 출력하는 예제가 들어 있습니다.

cat .python-version

3.15

cat main.py

def main():
    print("Hello from hello-python!")


if __name__ == "__main__":
    main()

프로젝트 파일은 uv run으로 실행합니다. 처음 실행하면 가상환경(.venv)을 만든 뒤 실행합니다.

uv run main.py

Using CPython 3.15.0
Creating virtual environment at: .venv
Hello from hello-python!

패키지는 uv add로 설치합니다. HTTP 요청을 보내는 requests 패키지를 설치해 봅니다. 설치한 패키지는 프로젝트의 가상환경에만 들어가고, pyproject.toml에 기록됩니다.

uv add requests

Resolved 6 packages in 189ms
Prepared 5 packages in 35ms
Installed 5 packages in 9ms
 + certifi==2026.7.22
 + charset-normalizer==3.5.2
 + idna==3.20
 + requests==2.34.2
 + urllib3==2.8.0

main.py를 requests를 쓰는 코드로 바꾸고 실행합니다. 첫 줄은 따옴표 안의 내용으로 파일을 만드는 명령이라 출력이 없습니다.

echo "import sys, requests; print('Hello Python', sys.version.split()[0], 'requests', requests.__version__)" > main.py
uv run main.py

Hello Python 3.15.0 requests 2.34.2

같은 파일을 python으로 바로 실행하면 requests를 찾을 수 없다는 오류가 납니다. requests는 프로젝트의 가상환경에만 설치되어 있기 때문입니다.

python main.py

Traceback (most recent call last):
  File "/home/devuser/hello-python/main.py", line 1, in <module>
    import sys, requests; print('Hello Python', sys.version.split()[0], 'requests', requests.__version__)
    ^^^^^^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'requests'

uv run 없이 python으로 실행하고 싶다면 가상환경을 켭니다(activate). 켜는 명령은 출력이 없습니다. 끝나면 deactivate로 끕니다.

source .venv/bin/activate

python --version

Python 3.15.0

python main.py

Hello Python 3.15.0 requests 2.34.2

deactivate

8. 프로젝트마다 Python 버전 정하기

프로젝트를 만들 때 --python으로 버전을 정할 수 있습니다. 홈 폴더로 돌아가서 Python 3.13을 쓰는 old-project를 만듭니다.

cd ~

uv init --no-package --python 3.13 old-project

Initialized project `old-project` at `/home/devuser/old-project`

cd old-project

cat .python-version

3.13

uv run python --version으로 이 프로젝트에서 실행되는 Python을 확인합니다.

uv run python --version

Using CPython 3.13.16
Creating virtual environment at: .venv
Python 3.13.16

나중에 버전을 올릴 때는 uv python pin을 씁니다. .python-version 파일이 바뀌고, 다음 실행 때 가상환경을 새 버전으로 다시 만듭니다.

uv python pin 3.15

Updated `.python-version` from `3.13` -> `3.15`

uv run python --version

Using CPython 3.15.0
Removed virtual environment at: .venv
Creating virtual environment at: .venv
Python 3.15.0

반대로 낮은 버전으로는 바로 내릴 수 없습니다. 9단계의 「requires-python」 항목을 참고하세요.

9. 문제 해결

python main.py

Traceback (most recent call last):
  File "/home/devuser/hello-python/main.py", line 1, in <module>
    import sys, requests; print('Hello Python', sys.version.split()[0], 'requests', requests.__version__)
    ^^^^^^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'requests'

uv python pin 3.13

error: The requested Python version `3.13` is incompatible with the project `requires-python` value of `>=3.15`.

pip3 install requests

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    …

10. 삭제하기

홈 폴더로 돌아가서 uv로 설치한 Python을 모두 삭제합니다. python, python3 등 ~/.local/bin에 등록한 이름도 함께 지워집니다. 시스템 Python은 지워지지 않습니다.

cd ~

uv python uninstall --all

Searching for Python installations
Uninstalled 2 versions in 118ms
 - cpython-3.13.16-linux-x86_64-gnu (python3.13)
 - cpython-3.15.0-linux-x86_64-gnu (python, python3, python3.15)

uv가 내려받은 파일을 보관하는 캐시를 지웁니다.

uv cache clean

Clearing cache at: .cache/uv
Removed 156 files (1.0MiB)

uv 도구 폴더와 연습용 프로젝트 폴더를 지우고, uv 프로그램과 PATH 설정 파일(env, env.fish)을 지웁니다. 두 명령 모두 출력이 없습니다.

rm -rf "$(uv tool dir)" ~/hello-python ~/old-project
rm ~/.local/bin/uv ~/.local/bin/uvx ~/.local/bin/env ~/.local/bin/env.fish

3단계에서 ~/.bashrc와 ~/.profile에 추가된 줄을 확인하고 지웁니다. sed -i는 파일을 바로 고친다는 뜻이고, /local\/bin\/env/d는 local/bin/env가 들어간 줄을 지운다는 뜻입니다.

grep -n 'local/bin/env' ~/.bashrc ~/.profile

/home/devuser/.bashrc:119:. "$HOME/.local/bin/env"
/home/devuser/.profile:29:. "$HOME/.local/bin/env"

sed -i '/local\/bin\/env/d' ~/.bashrc ~/.profile

ls -a ~/.local/bin

.  ..

터미널을 닫고 새로 열어 확인합니다. uv를 찾을 수 없고, python3가 시스템 Python으로 돌아왔으면 삭제된 것입니다.

uv --version

uv: command not found

python3 --version

Python 3.14.4