Django URL 설정 — 중복 걱정 없이 앱을 구성하는 3가지 핵심 원리

Django를 처음 배울 때 가장 많이 막히는 지점이 있다. “앱이 여러 개인데, URL이 겹치면 어떻게 되지?” 현장 엔지니어 출신으로 코드를 처음 배울 때 이 질문이 머릿속을 가장 오래 맴돌았다. 설비를 여러 대 관리할 때 장비 ID가 겹치면 이력이 뒤섞이듯, Django URL도 겹치면 뭔가 큰 문제가 생길 것 같은 느낌이었다.

결론부터 말한다. Django URL 설정은 구조적으로 중복이 불가능하게 설계되어 있다. 그 이유를 지금 하나씩 짚어보자.

Django URL은 2단계로 관리된다

Django URL은 두 층위에서 나눠서 관리한다.

앱 수준에서는 그 앱이 다루는 기능만 정의하면 된다. 로그인, 회원가입처럼 accounts 앱에서 쓸 Django URL만 모아두는 식이다. 그리고 이 앱별 URL들을 프로젝트 단위에서 include()로 연결할 때 각각 다른 경로(prefix)를 붙인다. 이것이 중복이 발생하지 않는 첫 번째 이유다.

include()가 만드는 Django URL 핵심 구조

프로젝트 단위 urls.py를 보면 이런 형태로 작성한다.

from django.urls import path, include

urlpatterns = [
    path('', include('main.urls')),             # 메인 앱: 루트 경로
    path('users/', include('accounts.urls')),   # accounts 앱: /users/ 경로
]

accounts 앱 내부에 sso-login/이라는 Django URL을 정의했다고 해보자.

# accounts/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('sso-login/', views.sso_login, name='sso_login'),
]

이때 최종 URL은 127.0.0.1:8000/users/sso-login/이 된다. 앱 내부의 경로 앞에 프로젝트 단에서 붙인 users/가 자동으로 앞에 붙기 때문이다.

만약 메인 앱에도 sso-login/이라는 이름이 있다 해도 최종 경로는 127.0.0.1:8000/sso-login/이 되어 완전히 다른 Django URL이 된다. 앱 단에서 이름이 같아도, 프로젝트 단에서 prefix가 갈리기 때문에 중복이 발생하지 않는다.

앱 이름을 prefix로 쓰는 이유 — Django URL 중복을 고민조차 안 해도 되는 구조

강제된 규칙은 아니지만, 실무에서는 앱 이름을 그대로 prefix로 쓰는 것이 관례다.

path('accounts/', include('accounts.urls')),
path('products/', include('products.urls')),

이유는 단순하다. 앱 이름은 Django 프로젝트 내에서 중복이 허용되지 않는다. 이미 유일성이 보장된 앱 이름을 prefix로 사용하면, Django URL 중복 여부를 신경 쓸 필요 자체가 없어진다.

앱 단위에서 URL 이름이 겹치든 아니든, 프로젝트 단에서 이미 구조적으로 분리되어 있기 때문이다. 입문자가 가장 많이 걱정하는 “URL 이름이 같으면 어떡하지?”라는 고민은 이 구조를 이해하는 순간 사라진다.

핵심 요약

• Django URL은 프로젝트 단위와 앱 단위 2단계로 관리된다
• include()로 앱별 urls.py를 연결할 때 prefix를 붙이면 구조적으로 중복이 불가능해진다
• 앱 이름을 prefix로 쓰는 관례를 따르면 Django URL 중복을 고민할 필요 자체가 없다
• 처음부터 앱 단위로 URLs를 분리하는 습관을 들이면 앱이 늘어나도 관리가 쉬워진다

[링크 제안]

Django URL 구조를 이해했다면, URL·View·Template이 어떻게 연결되는지 전체 흐름도 함께 잡아두자.

• Django 구조 완전 정복 — URL·View·Template 3파일 흐름을 3단계로 이해하는 법

Django 모델이 이 구조 위에서 어떻게 동작하는지도 함께 보면 전체 그림이 완성된다.

• Django 모델이 핵심인 3가지 이유 — ORM·검증·Migration 한 번에 해결

자비스는 어떻게 만들어졌을까 — Agentic AI의 시작

FAQ