1. get_valid_filename이란?

django.utils.text.get_valid_filename은 문자열을 파일 시스템에서 안전하게 사용할 수 있는 파일명으로 변환해 주는 작은 헬퍼 함수입니다.
Windows, macOS, Linux 등 대부분의 운영체제에서 금지되거나 문제가 되는 문자(슬래시, 제어 문자 등)를 제거하거나 바꾸고, 문자열을 예측 가능한 형식으로 정규화합니다.

왜 필요한가?
사용자가 파일을 업로드하거나 임의의 입력(예: 블로그 제목, 사용자 태그)으로 파일명을 만들 때, 슬래시(../etc/passwd) 같은 디렉터리 트래버설이나 비정상적인 문자를 포함하면 파일 시스템이 깨지거나 보안 취약점이 생길 수 있습니다.

2. 동작 방식

from django.utils.text import get_valid_filename

raw = "My: New/Project? 2024*"
safe = get_valid_filename(raw)
print(safe)   # → "My_New_Project_2024"

주요 동작

입력 결과 설명
"my file.txt" "my_file.txt" 공백 → 밑줄
"../etc/passwd" "etc_passwd" 앞의 점·슬래시 제거
"file<name>.txt" "file_name_.txt" <·> 바뀜
" " "" 공백만 있으면 빈 문자열
"a"*300 "a"*255 파일 시스템 한계(255자)까지 잘라냄

함수는 크로스 플랫폼으로, 안전한 문자 집합([A-Za-z0-9_.-])만 허용하고 나머지는 밑줄(_)로 바꿉니다.

3. 유용한 상황

상황 필요성
사용자 업로드 디렉터리 트래버설(../../etc/passwd)과 금지 문자를 방지
슬러그 기반 파일명 블로그 제목을 정적 사이트용 파일명으로 변환
데이터 내보내기 데이터베이스 필드(쉼표, 따옴표 등)를 포함한 CSV/JSON 파일명 생성
자동 백업 임의 문자열에서 타임스탬프가 포함된 백업 파일명 생성

4. 실전 예시: 이미지 업로드 저장

# views.py
from django.shortcuts import render
from django.core.files.storage import default_storage
from django.utils.text import get_valid_filename

def upload_image(request):
    if request.method == 'POST':
        uploaded = request.FILES['image']
        # 원본 파일명 정리
        safe_name = get_valid_filename(uploaded.name)
        # 필요 시 유저 ID 또는 타임스탬프 추가
        final_name = f"{request.user.id}_{safe_name}"
        path = default_storage.save(f"uploads/{final_name}", uploaded)
        return render(request, 'success.html', {'path': path})
    return render(request, 'upload.html')

결과
사용자가 파일명을 어떻게 지정하든 저장되는 이름은 안전하고, 디렉터리 트래버설이 없으며, 중복 가능성이 낮아집니다.

5. 빠른 참고

from django.utils.text import get_valid_filename

# 1. 기본 정리
safe = get_valid_filename("My: New/Project? 2024*")  # → "My_New_Project_2024"

# 2. 파일 경로에 사용
path = f"media/{safe}.jpg"

# 3. UUID와 결합해 고유성 확보
import uuid
unique_name = f"{uuid.uuid4().hex}_{safe}.jpg"

6. 핵심 정리

  • get_valid_filename은 한 줄 코드로 파일 시스템을 위험한 이름으로부터 보호합니다.
  • 사용자 입력이나 임의 문자열을 파일명으로 변환할 때마다 사용하세요.
  • 코드가 깔끔하고, 크로스 플랫폼이며, 보안적으로 안전합니다.

팁: 공백을 그대로 두거나 유니코드를 보존해야 할 경우 slugify와 결합하거나 커스텀 헬퍼를 만들 수 있지만, 대부분의 경우 get_valid_filename이 가장 적합합니다.