uv로 프로젝트 환경 셋팅하기

네이버 부캠에서 리뷰 감성 분류 챌린지를 하는데 venv 대신 uv를 사용해보면 더 빠르고 좋다고 해서 이번 기회에 써보려한다

셋팅하느라 헷갈리는 부분들이 생기기도 해서 그냥 셋팅 과정을 간단한 메모로 남겨두고 나중에 참고하려 끄적이기

아래는 참고 자료들

💻 내가 보려고 작성한 UV 완벽 가이드

이 가이드에서는 UV의 핵심 기능과 실무 적용 방법을 상세히 알아보겠습니다.

velog.io

PIP를 대체하는 UV 사용법 가이드

devocean.sk.com

Text Classification 대회 uv 셋업

도커 컨테이너 환경으로 되어 있는 서버에 uv로 프로젝트 환경 셋팅하려 한다

uv 설치 전에 서버는 완전 깡통이니까... 설치 명령어 실행할 수 있게끔 curl 먼저 설치해주기

apt update
apt install curl -y

uv 설치

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

root@instance-16554:~/project: curl -LsSf https://astral.sh/uv/install.sh | sh
downloading uv 0.9.5 x86_64-unknown-linux-gnu
no checksums to verify
installing to /data/ephemeral/home/.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 명령어가 제대로 인식되는데 아래처럼 bashrc에 저장해두면 서버 접속할 때마다 실행되어 매번 다시 패스를 잡아줄 필요가 없어진다

# bash를 사용하는 경우
echo 'export PATH=/data/ephemeral/home/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

root@instance-16554:~/project: export PATH=/data/ephemeral/home/.local/bin:$PATH
root@instance-16554:~/project: which uv
/data/ephemeral/home/.local/bin/uv
root@instance-16554:~/project: uv --version
uv 0.9.5

파이썬 3.10 버젼 설치

root@instance-16554:~/project: uv python install 3.10
Installed Python 3.10.19 in 9.60s
 + cpython-3.10.19-linux-x86_64-gnu (python3.10)

프로젝트 생성

미리 만들어 둔 project 디렉토리에서 아래 명령어를 실행하면 아래처럼 해당 디렉토리 아래 여러 파일들이 생성된다

root@instance-16554:~/project: uv init
Initialized project `project`

uv init으로는 이런 초기화 작업만 해주지 가상 환경을 생성해주지는 않는다고 한다

가상환경 생성

root@instance-16554:~/project: uv venv -p 3.10 .py310
Using CPython 3.10.19
Creating virtual environment at: .py310
Activate with: source .py310/bin/activate

root@instance-16554:~/project: uv sync
Using CPython 3.10.19
Creating virtual environment at: .venv
Resolved 1 package in 14ms
Audited in 0.00ms

uv venv를 통해 원하는 파이썬 버전의 가상환경 생성한다

그리고 requirements.txt가 있을 경우

uv pip install -r requirements.txt

uv sync

작업 효과

현재 프로젝트에 정의된 패키지 잠금 파일(uv.lock) 기준으로 venv를 동기화
uv.lock에 없는 패키지는 삭제, 있는 패키지는 설치/업데이트
즉, 환경을 선언적 상태로 유지

장점

재현 가능 환경 : 다른 머신에서도 uv.lock만 있으면 동일한 환경을 만들 수 있음
불필요한 패키지 제거 : 개발 도중 설치했다가 사용하지 않는 패키지 삭제 가능
팀 단위 협업 : uv.lock을 공유 → 팀원이 동일한 환경 구성 가능
간편한 업그레이드/복구 : 환경 꼬였을 때 uv sync로 한 번에 초기화 가능

오... 확실히 편해보인다. 관리만 잘 해두면 그대로 가져가서 다른 곳에서도 빠르게 셋팅이 가능하고 편리할 것 같다

여기서 기본적인 툴들 설치하고 주피터 노트북이랑 ipykernel 등 설치해서 작업 환경까지.

챌린지 하다보니 서버가 갑자기 종료되고 팅기는 이슈들이 종종 발생해서 새로 셋팅해야할 일이 자주 있을 것 같아 GPT의 도움을 받아 한번에 셋업할 수 있는 형태로, 쉘 스크립트로 정리해보았다

완전 자동화: 빈 서버에서 setup.sh와 requirements.txt만으로 환경을 세팅 가능.
uv 기반: pip가 아니라 uv를 이용해 가상환경(.venv)과 의존성 설치를 관리.
Python 3.10 고정: 지정한 Python 인터프리터(/opt/conda/bin/python3.10) 사용.
Jupyter 호환: ipykernel 설치 및 커널 등록으로 노트북에서 바로 사용 가능.
VSCode 지원: .vscode/settings.json 생성, 가상환경 연결 및 lint 활성화.
프로젝트 구조 초기화: src, notebooks, data 폴더와 기본 파일 생성.

#!/bin/bash
# =========================================
# /data/ephemeral uv project setup script (uv-only, Python 3.10)
# Python 3.10, uv venv (.venv), Jupyter kernel, VSCode
# =========================================

set -e

# 1. Set project paths
PROJECT_DIR="/data/ephemeral/home/my_project"
UV_BIN="/data/ephemeral/home/.local/bin/uv"
PYTHON_ENV_NAME="py310"
REQUIREMENTS_FILE="/data/ephemeral/home/requirements.txt"
PYTHON_INTERPRETER="/opt/conda/bin/python3.10"

echo "Step 1: Creating and initializing project folder: $PROJECT_DIR"
mkdir -p "$PROJECT_DIR"
cd "$PROJECT_DIR"
rm -rf * .??*   # Remove existing content (irreversible)

# 2. Add uv to PATH
export PATH="$UV_BIN:$PATH"

# 3. Initialize uv project
echo "Step 2: Initializing uv project"
$UV_BIN init

# 4. Create uv virtual environment in default .venv using Python 3.10
echo "Step 3: Creating uv venv in .venv with Python 3.10"
$UV_BIN venv --python "$PYTHON_INTERPRETER"

# 5. Install packages from requirements.txt using uv add
if [ -f "$REQUIREMENTS_FILE" ]; then
    echo "Step 4: Installing packages from $REQUIREMENTS_FILE via uv add"
    $UV_BIN add -r "$REQUIREMENTS_FILE"
else
    echo "Step 4: No requirements.txt found, skipping package installation"
fi

# 6. Install ipykernel via uv add
echo "Step 5: Installing ipykernel via uv add"
$UV_BIN add ipykernel

# 7. Sync uv environment
echo "Step 6: Syncing uv environment"
$UV_BIN sync

# 8. Register Jupyter kernel
echo "Step 7: Registering Jupyter kernel"
source .venv/bin/activate
python -m ipykernel install --user --name $PYTHON_ENV_NAME --display-name "Python ($PYTHON_ENV_NAME)"

# 9. Create project structure
echo "Step 8: Creating project structure"
mkdir -p src notebooks data
touch src/main.py

# 10. VSCode settings
echo "Step 9: Creating VSCode settings"
mkdir -p .vscode
cat > .vscode/settings.json <<EOL
{
    "python.defaultInterpreterPath": "\${workspaceFolder}/.venv/bin/python",
    "python.terminal.activateEnvironment": true,
    "python.linting.enabled": true
}
EOL

echo "Setup complete!"
echo "Project location: $PROJECT_DIR"
echo "Virtual environment: $PROJECT_DIR/.venv"
echo "Python version: $(.venv/bin/python --version)"
echo "Jupyter kernel name: $PYTHON_ENV_NAME"
echo "Requirements installed from: $REQUIREMENTS_FILE"
echo "Ready to use in VSCode"

제대로 셋팅이 되었다면 아래처럼 등록한 주피터 커널이 나온다

그리고 requirements.txt에 있는 모듈들도 import하면 정상적으로 동작한다

✅ 사용 방법

1. setup.sh와 requirements.txt를 같은 디렉토리에 두기

2. 터미널에서 실행:

bash setup.sh

3. 완료 후 VSCode에서 .venv/bin/python을 인터프리터로 지정

이런 식으로 구성된다

여기에 따로 빼두었던 데이터랑 코드들 다시 업로드하면 셋팅 끝!

requirements.txt 경로 제대로 설정안해서 가상환경 만들고 주피터 노트북 커널 등록까지 제대로 되었는데도 uv add가 안되서 가상환경에 디피션시 반영이 안되는 것 때문에 많이 헤메느라 제대로 동작하기까지 4시간이나 걸려버렸다...

그래도 확실히 pip install -r requirements.txt pip 설치보다는 속도가 많이 빠른게 체감이 되었다

아래는 깡통 서버에서 setup.sh랑 requirements.txt 두 개 파일만 넣고 스크립트 하나 딸깍으로 셋팅하는 쉘스크립트이다

다음에 또 서버 터지면 써보고 잘 동작하는지 확인해봐야겠다

#!/bin/bash
# =========================================
# Complete server setup with uv (Python 3.10)
# Requires: root
# =========================================

set -e

# --------------------------
# 0. Basic server setup
# --------------------------
echo "Step 0: Updating apt and installing curl"
apt update
apt install -y curl

# --------------------------
# 1. Install uv
# --------------------------
echo "Step 1: Installing uv"
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add uv to PATH automatically for future sessions
echo 'export PATH=/data/ephemeral/home/.local/bin:$PATH' >> ~/.bashrc
export PATH=/data/ephemeral/home/.local/bin:$PATH

# --------------------------
# 2. Project paths
# --------------------------
PROJECT_DIR="/data/ephemeral/home/my_project"
PYTHON_ENV_NAME="py310"
REQUIREMENTS_FILE="/data/ephemeral/home/requirements.txt"
PYTHON_INTERPRETER="/opt/conda/bin/python3.10"

echo "Step 2: Creating and initializing project folder: $PROJECT_DIR"
mkdir -p "$PROJECT_DIR"
cd "$PROJECT_DIR"
rm -rf * .??*   # Remove existing content

# --------------------------
# 3. Initialize uv project
# --------------------------
echo "Step 3: Initializing uv project"
uv init

# --------------------------
# 4. Create uv virtual environment
# --------------------------
echo "Step 4: Creating uv venv in .venv with Python 3.10"
uv venv --python "$PYTHON_INTERPRETER"

# --------------------------
# 5. Install packages from requirements.txt
# --------------------------
if [ -f "$REQUIREMENTS_FILE" ]; then
    echo "Step 5: Installing packages from $REQUIREMENTS_FILE via uv add"
    uv add -r "$REQUIREMENTS_FILE"
else
    echo "Step 5: No requirements.txt found, skipping package installation"
fi

# --------------------------
# 6. Install ipykernel
# --------------------------
echo "Step 6: Installing ipykernel via uv add"
uv add ipykernel

# --------------------------
# 7. Sync uv environment
# --------------------------
echo "Step 7: Syncing uv environment"
uv sync

# --------------------------
# 8. Register Jupyter kernel
# --------------------------
echo "Step 8: Registering Jupyter kernel"
source .venv/bin/activate
python -m ipykernel install --user --name $PYTHON_ENV_NAME --display-name "Python ($PYTHON_ENV_NAME)"

# --------------------------
# 9. Create project structure
# --------------------------
echo "Step 9: Creating project structure"
mkdir -p src notebooks data
touch src/main.py

# --------------------------
# 10. VSCode settings
# --------------------------
echo "Step 10: Creating VSCode settings"
mkdir -p .vscode
cat > .vscode/settings.json <<EOL
{
    "python.defaultInterpreterPath": "\${workspaceFolder}/.venv/bin/python",
    "python.terminal.activateEnvironment": true,
    "python.linting.enabled": true
}
EOL

# --------------------------
# 11. Finish
# --------------------------
echo "Setup complete!"
echo "Project location: $PROJECT_DIR"
echo "Virtual environment: $PROJECT_DIR/.venv"
echo "Python version: $(.venv/bin/python --version)"
echo "Jupyter kernel name: $PYTHON_ENV_NAME"
echo "Requirements installed from: $REQUIREMENTS_FILE"
echo "Ready to use in VSCode"

Object Detection 대회 서버 셋업

uv로 가상환경 만들고 부캠측이 공유해준 베이스라인을 셋업하다보면 여러 이슈들이 발생한다

에러는 따로 적진 않았지만 서버 기본 메뉴얼에서 가상 환경의 파이썬 버전을 3.11을 사용하는데 MMDetection을 사용하려 할 경우 3.8이상 3.11미만 버전을 사용하기 때문에 버전 이슈도 발생했었다

그래서 가상환경 파이썬 버전은 3.10을 사용하였다

그 뒤에도 같이 들어있는 setup.py를 실행하여 셋팅한 뒤에 베이스라인 코드를 실행하다보면 아래의 에러를 만나게 된다

실제 베이스라인 코드 대신 해당 모듈을 불러오는 코드로 테스트해봐도 동일

from mmdet.utils import register_all_modules
register_all_modules(init_default_scope=True)

>> ModuleNotFoundError: No module named 'mmcv._ext'

---------------------------------------------------------------------------
ModuleNotFoundError                       Traceback (most recent call last)
Cell In[2], line 11
      9 # config file 들고오기
     10 cfg = Config.fromfile("configs/faster_rcnn/faster-rcnn_r50_fpn_1x_coco.py")
---> 11 register_all_modules(init_default_scope=True)
     12 cfg.default_scope = "mmdet"
     14 # dataset config 수정

File ~/baseline/mmdetection/mmdet/utils/setup_env.py:97, in register_all_modules(init_default_scope)
     86 def register_all_modules(init_default_scope: bool = True) -> None:
     87     """Register all modules in mmdet into the registries.
     88 
     89     Args:
   (...)
     95             Defaults to True.
     96     """  # noqa
---> 97     import mmdet.datasets  # noqa: F401,F403
     98     import mmdet.engine  # noqa: F401,F403
     99     import mmdet.evaluation  # noqa: F401,F403

File ~/baseline/mmdetection/mmdet/datasets/__init__.py:31
     26 from .reid_dataset import ReIDDataset
     27 from .samplers import (AspectRatioBatchSampler, ClassAwareSampler,
     28                        CustomSampleSizeSampler, GroupMultiSourceSampler,
     29                        MultiSourceSampler, TrackAspectRatioBatchSampler,
     30                        TrackImgSampler)
---> 31 from .utils import get_loading_pipeline
     32 from .v3det import V3DetDataset
     33 from .voc import VOCDataset

File ~/baseline/mmdetection/mmdet/datasets/utils.py:5
      1 # Copyright (c) OpenMMLab. All rights reserved.
      3 from mmcv.transforms import LoadImageFromFile
----> 5 from mmdet.datasets.transforms import LoadAnnotations, LoadPanopticAnnotations
      6 from mmdet.registry import TRANSFORMS
      9 def get_loading_pipeline(pipeline):

File ~/baseline/mmdetection/mmdet/datasets/transforms/__init__.py:6
      2 from .augment_wrappers import AutoAugment, RandAugment
      3 from .colorspace import (AutoContrast, Brightness, Color, ColorTransform,
      4                          Contrast, Equalize, Invert, Posterize, Sharpness,
      5                          Solarize, SolarizeAdd)
----> 6 from .formatting import (ImageToTensor, PackDetInputs, PackReIDInputs,
      7                          PackTrackInputs, ToTensor, Transpose)
      8 from .frame_sampling import BaseFrameSample, UniformRefFrameSample
      9 from .geometric import (GeomTransform, Rotate, ShearX, ShearY, TranslateX,
     10                         TranslateY)

File ~/baseline/mmdetection/mmdet/datasets/transforms/formatting.py:11
      9 from mmdet.registry import TRANSFORMS
     10 from mmdet.structures import DetDataSample, ReIDDataSample, TrackDataSample
---> 11 from mmdet.structures.bbox import BaseBoxes
     14 @TRANSFORMS.register_module()
     15 class PackDetInputs(BaseTransform):
     16     """Pack the inputs data for the detection / semantic segmentation /
     17     panoptic segmentation.
     18 
   (...)
     42             'scale_factor', 'flip', 'flip_direction')``
     43     """

File ~/baseline/mmdetection/mmdet/structures/bbox/__init__.py:2
      1 # Copyright (c) OpenMMLab. All rights reserved.
----> 2 from .base_boxes import BaseBoxes
      3 from .bbox_overlaps import bbox_overlaps
      4 from .box_type import (autocast_box_type, convert_box_type, get_box_type,
      5                        register_box, register_box_converter)

File ~/baseline/mmdetection/mmdet/structures/bbox/base_boxes.py:9
      6 import torch
      7 from torch import BoolTensor, Tensor
----> 9 from mmdet.structures.mask.structures import BitmapMasks, PolygonMasks
     11 T = TypeVar('T')
     12 DeviceType = Union[str, torch.device]

File ~/baseline/mmdetection/mmdet/structures/mask/__init__.py:3
      1 # Copyright (c) OpenMMLab. All rights reserved.
      2 from .mask_target import mask_target
----> 3 from .structures import (BaseInstanceMasks, BitmapMasks, PolygonMasks,
      4                          bitmap_to_polygon, polygon_to_bitmap)
      5 from .utils import encode_mask_results, mask2bbox, split_combined_polys
      7 __all__ = [
      8     'split_combined_polys', 'mask_target', 'BaseInstanceMasks', 'BitmapMasks',
      9     'PolygonMasks', 'encode_mask_results', 'mask2bbox', 'polygon_to_bitmap',
     10     'bitmap_to_polygon'
     11 ]

File ~/baseline/mmdetection/mmdet/structures/mask/structures.py:12
     10 import shapely.geometry as geometry
     11 import torch
---> 12 from mmcv.ops.roi_align import roi_align
     14 T = TypeVar('T')
     17 class BaseInstanceMasks(metaclass=ABCMeta):

File ~/baseline/.venv/lib/python3.10/site-packages/mmcv/ops/__init__.py:3
      1 # Copyright (c) OpenMMLab. All rights reserved.
      2 from mmcv.utils import IS_MLU_AVAILABLE
----> 3 from .active_rotated_filter import active_rotated_filter
      4 from .assign_score_withk import assign_score_withk
      5 from .ball_query import ball_query

File ~/baseline/.venv/lib/python3.10/site-packages/mmcv/ops/active_rotated_filter.py:10
      6 from torch.autograd.function import once_differentiable
      8 from ..utils import ext_loader
---> 10 ext_module = ext_loader.load_ext(
     11     '_ext',
     12     ['active_rotated_filter_forward', 'active_rotated_filter_backward'])
     15 class ActiveRotatedFilterFunction(Function):
     16     """Encoding the orientation information and generating orientation-
     17     sensitive features.
     18 
     19     The details are described in the paper `Align Deep Features for Oriented
     20     Object Detection  <https://arxiv.org/abs/2008.09397>_`.
     21     """

File ~/baseline/.venv/lib/python3.10/site-packages/mmcv/utils/ext_loader.py:13, in load_ext(name, funcs)
     12 def load_ext(name, funcs):
---> 13     ext = importlib.import_module('mmcv.' + name)
     14     for fun in funcs:
     15         assert hasattr(ext, fun), f'{fun} miss in module {name}'

File ~/.local/share/uv/python/cpython-3.10.19-linux-x86_64-gnu/lib/python3.10/importlib/__init__.py:126, in import_module(name, package)
    124             break
    125         level += 1
--> 126 return _bootstrap._gcd_import(name[level:], package, level)

ModuleNotFoundError: No module named 'mmcv._ext'

현재 사용하고 있는 서버의 쿠다, torch 등의 버젼과 설치하려는 MMDetection의 라이브러리 버전들이 안맞아서 발생하는 일

uv 가상환경 셋업

# 프로젝트 위치에서 실행
uv venv --python 3.10
uv pip install -r requirements.txt
uv pip install pip

# 가상환경 활성화 +pip 최신화
source .venv/bin/activate
pip install -U pip

# 주피터 노트북에 가상환경 커널 등록
uv pip install ipykernel
python -m ipykernel install --user --name baseline --display-name "Python (baseline)"

PyTorch 2.1.0 + cu121 설치

pip install torch==2.1.0 --index-url https://download.pytorch.org/whl/cu121

정상 설치시 버젼

import torch
print("torch:", torch.__version__)
print("cuda :", torch.version.cuda)

>>
torch: 2.1.0+cu121
cuda : 12.1

torchvision 설치 (torch 2.1.0과 호환되는 버전)

pip install torchvision==0.16.0 --index-url https://download.pytorch.org/whl/cu121

import torchvision
print("vision:", torchvision.__version__)

openmim, MMEngine 설치

pip install -U openmim
mim install mmengine

MMCV 2.1.0 cu121 + torch2.1 wheel 설치

⚠️ 절대 pip install mmcv 하면 안 됨
⚠️ 반드시 아래 인덱스를 사용해야 _ext CUDA 모듈이 포함된 wheel이 설치됨

pip install "mmcv==2.1.0" -f https://download.openmmlab.com/mmcv/dist/cu121/torch2.1/index.html

MMDetection 설치

mim install "mmdet==3.3.0"

최종체크

import mmcv, os, glob
mmcv_dir = os.path.dirname(mmcv.__file__)
print("ext:", glob.glob(os.path.join(mmcv_dir, "_ext*")))

>>
ext: ['/data/ephemeral/home/baseline/.venv/lib/python3.10/site-packages/mmcv/_ext.cpython-310-x86_64-linux-gnu.so']

_ext 모듈이 정상적으로 위치한 것 확인

from mmdet.utils import register_all_modules
register_all_modules(init_default_scope=True)
print("MMDetection OK")

>>
MMDetection OK

모듈 정상적으로 호출도 확인 완료
학습도 정상적으로 동작

'공부기록 > 깃 & 리눅스' 카테고리의 다른 글

[강의] 개발자스럽게 Github 사용하기 (0)	2025.11.13
리눅스 디렉토리 내 용량 확인 (0)	2025.10.28
Git & Github 실무 활용 완벽 가이드 part2. (브랜치와 변경사항 처리 방법) (0)	2024.11.02
Git & Github 실무 활용 완벽 가이드 part1. (Git 기초 및 커밋) (0)	2024.04.12

𝙴𝚅𝙴𝚁𝚈𝚃𝙷𝙸𝙽𝙶 𝙸𝚂 𝙽̶𝙾̶𝚃̶ 𝙾𝙺

uv로 프로젝트 환경 셋팅하기

Text Classification 대회 uv 셋업

Object Detection 대회 서버 셋업

uv 가상환경 셋업

PyTorch 2.1.0 + cu121 설치

torchvision 설치 (torch 2.1.0과 호환되는 버전)

openmim, MMEngine 설치

MMCV 2.1.0 cu121 + torch2.1 wheel 설치

MMDetection 설치

최종체크

'공부기록 > 깃 & 리눅스' 카테고리의 다른 글

티스토리툴바

uv로 프로젝트 환경 셋팅하기

Text Classification 대회 uv 셋업

Object Detection 대회 서버 셋업

uv 가상환경 셋업

PyTorch 2.1.0 + cu121 설치

torchvision 설치 (torch 2.1.0과 호환되는 버전)

openmim, MMEngine 설치

MMCV 2.1.0 cu121 + torch2.1 wheel 설치

MMDetection 설치

최종체크

'공부기록 > 깃 & 리눅스' 카테고리의 다른 글

관련글

티스토리툴바