Python과 Django 웹 개발 시작하기: 초보자를 위한 튜토리얼

Python과 Django는 웹 개발을 시작하려는 초보자에게 인기 있는 조합입니다. 이 튜토리얼에서는 Python 설치부터 가상환경 설정, Django 설치 및 “Hello, Django!” 페이지를 띄우기까지의 과정을 단계별로 알아보겠습니다. 각 단계마다 따라하기 쉬운 설명과 명령어, 그리고 예상 결과나 주의사항을 함께 제공합니다. 이 글에서는 Python 3.x 버전을 전제로 하며 (최신 Django는 Python 3.10 이상이 필요), Windows와 Mac 환경을 중심으로 설명합니다. 이제 시작해봅시다!

1. Python 설치 (Windows/Mac)

먼저 Python이 설치되어 있어야 합니다. Python이 이미 설치되어 있는지 확인하려면 터미널(또는 명령 프롬프트)을 열고 버전을 확인해보세요:

$ python --version
Python 3.11.5

위와 비슷한 출력이 나오면 Python이 설치되어 있는 것입니다 (버전 번호는 다를 수 있습니다). 만약 Python을 설치하지 않았다면, 아래의 방법으로 설치하세요:

• Windows: Python 공식 웹사이트에서 Windows용 설치 파일을 다운로드하여 실행하세요. 설치 마법사에서 “Add Python to PATH” 옵션을 선택하면 편리합니다. 설치가 끝나면 새로운 명령 프롬프트를 열고 python --version으로 정상 설치 여부를 확인하세요.
• Mac: macOS에 기본 Python이 포함되어 있을 수 있지만 최신 버전이 아닐 수도 있습니다 (또는 Python 2.x가 포함된 경우가 있습니다). 최신 Python 3을 사용하기 위해 Python 공식 사이트에서 macOS용 Python 3 설치 패키지를 받아 설치하거나, Homebrew를 사용 중이라면 터미널에 brew install python3 명령으로 설치할 수 있습니다. 설치 후 터미널을 새로 열고 python3 --version 명령으로 버전을 확인하세요 (Mac에서는 기본 python 명령이 다른 버전을 가리킬 수 있으므로 python3을 사용하는 것이 안전합니다).

※ 팁: 설치 후에도 python 명령을 인식하지 못한다면 시스템 PATH 설정에 Python이 추가되지 않은 경우입니다. 이때는 설치를 할 때 PATH 추가 옵션을 켰는지 확인하거나, Windows에서는 py 명령어를 대신 사용할 수도 있습니다 (py --version).

2. 가상환경 설정 (venv 사용)

Python 설치를 마쳤다면, 이제 **가상환경(virtual environment)**을 만들어 프로젝트별로 독립된 패키지 환경을 구성해보겠습니다. 가상환경을 사용하면 여러 프로젝트 간에 패키지 버전 충돌을 막을 수 있어 권장되는 좋은 습관입니다.

1. 프로젝트 폴더 생성: 작업할 폴더를 하나 만들어보겠습니다. 예를 들어 django_project라는 이름의 폴더를 만들고 그 폴더로 이동합니다:(이미 존재하는 폴더를 사용할 경우 이 단계는 생략합니다.)
2. $ mkdir django_project $ cd django_project
3. venv 모듈로 가상환경 생성: Python에는 내장 모듈인 venv로 가상환경을 생성할 수 있습니다. 터미널에서 아래 명령을 실행하세요:명령을 실행하면 현재 경로에 venv라는 이름의 폴더가 생성됩니다. 이 폴더 안에 가상환경에 필요한 파일들이 들어있습니다. (venv는 가상환경 이름으로 임의로 정할 수 있지만, 일반적으로 폴더 이름을 venv나 env로 많이 사용합니다.)
4. $ python -m venv venv
5. 가상환경 활성화: 가상환경을 만든 후에는 그것을 활성화(activate) 해야 해당 환경을 사용할 수 있습니다. OS에 따라 활성화 방법이 조금 다릅니다:
   • Windows (명령 프롬프트):
   • $ venv\Scripts\activate.bat
   • Windows (PowerShell):
   • $ venv\Scripts\Activate.ps1
   • Mac/Linux (터미널):
   • $ source venv/bin/activate
   위 명령을 실행하면 프롬프트 앞에 (venv)와 같은 가상환경 이름이 표시됩니다. 예를 들어:이런 식으로 된다면 가상환경 활성화에 성공한 것입니다. 이제 이 터미널에서는 pip으로 패키지를 설치해도 시스템 전체가 아니라 이 가상환경에만 설치되게 됩니다.
6. (venv) $
7. (선택) pip 업그레이드: 경우에 따라 기본 pip 버전이 오래되었을 수 있으므로, 필요하다면 pip install --upgrade pip 명령으로 pip 자체를 최신 버전으로 올릴 수 있습니다. 반드시 해야 하는 것은 아니지만, 패키지 설치 시 경고가 나오면 업그레이드하면 됩니다.

※ 비고: 가상환경을 종료하고 싶다면 deactivate 명령을 입력하면 됩니다 (활성화한 터미널에서만 유효).

3. Django 설치

가상환경을 활성화한 상태에서 Django 프레임워크를 설치해보겠습니다. Python의 패키지 관리 도구인 pip를 사용하여 설치할 수 있습니다. 터미널에 다음 명령어를 입력하세요:

(venv) $ pip install django

위 명령을 실행하면 인터넷에서 Django 패키지와 관련 의존성 패키지들을 다운로드하여 가상환경에 설치합니다. 설치 과정에서는 다운로드 진행률이 표시되고, 완료 후 다음과 유사한 메시지가 나타납니다:

Successfully installed Django-5.2.1 asgiref-3.7.2 sqlparse-0.4.4 tzdata-2023.3

(버전 숫자는 시점에 따라 달라질 수 있습니다.)
이렇게 나오면 Django 설치가 완료된 것입니다. 설치가 제대로 되었는지 확인해보고 싶다면 Django의 버전을 출력해볼 수 있습니다:

(venv) $ python -m django --version
5.2.1

위와 같이 Django의 버전 번호가 출력되면 문제없이 설치된 것입니다.

4. Django 프로젝트 생성 및 구조 설명

이제 Django 프로젝트를 생성해보겠습니다. 프로젝트는 Django 웹 애플리케이션의 전체 설정을 담는 공간입니다. 한 프로젝트 안에는 여러 앱(app)을 포함할 수 있습니다. Django에서는 django-admin이라는 명령어 도구를 제공하여 프로젝트를 손쉽게 만들 수 있습니다.

가상환경이 활성화된 터미널에서, 원하는 경로에 아래와 같이 django-admin startproject 명령을 실행하세요 (예제에서는 프로젝트 이름을 mysite로 정하겠습니다):

(venv) $ django-admin startproject mysite

명령을 실행하면 현재 폴더에 mysite라는 새 디렉토리가 생성됩니다. 프로젝트 이름으로 디렉토리가 생성되고, 그 안에 같은 이름의 하위 디렉토리가 함께 만들어지는 것이 정상입니다. 방금 생성된 프로젝트의 구조를 살펴보면 다음과 같습니다:

mysite/               # 프로젝트 폴더
    manage.py         # Django 관리 명령어 유틸리티
    mysite/           # 내부 프로젝트 패키지 (프로젝트 설정 폴더)
        __init__.py   # 패키지 초기화 파일 (내용 없음)
        settings.py   # 프로젝트 설정 파일
        urls.py       # 프로젝트 URL 설정 파일
        asgi.py       # ASGI 설정 (비동기 서버용)
        wsgi.py       # WSGI 설정 (전통적 웹 서버용)

위 구조에서 가장 바깥의 mysite/ 폴더가 프로젝트의 루트 디렉토리이고, 그 안에 manage.py 파일과 동일한 이름의 mysite/ 폴더가 하나 더 생성된 것을 볼 수 있습니다. 이 내부 mysite 폴더가 프로젝트 패키지로서, Django 설정과 URL 라우팅 등의 코드를 담고 있습니다. 주요 파일의 역할은 다음과 같습니다:

• manage.py: Django 프로젝트 관리를 위한 커맨드라인 유틸리티입니다. 개발 서버 실행, 앱 생성, 마이그레이션 등 각종 Django 명령을 이 파일을 통해 실행합니다.
• settings.py: 프로젝트의 설정 파일입니다. 데이터베이스 정보, 설치된 앱 목록(INSTALLED_APPS), 디버그 모드 여부 등 프로젝트 전반의 설정이 들어있습니다.
• urls.py: URL 패턴을 정의하는 곳입니다. 어떤 URL로 접근했을 때 어떤 코드(뷰 함수)가 실행될지를 맵핑합니다. 프로젝트의 전역 URL 설정을 담당합니다.
• asgi.py와 wsgi.py: 웹 서버와 Django를 연결해주는 인터페이스 설정 파일입니다. 개발 단계에서는 크게 신경 쓸 필요는 없지만, 배포 시에 사용됩니다 (ASGI는 비동기 지원 서버용, WSGI는 전통적인 웹서버용).
• __init__.py: mysite 폴더를 파이썬 패키지로 인식시키기 위한 파일로, 내용은 비어 있습니다.

프로젝트가 정상적으로 생성되었다면, 이제 해당 프로젝트 폴더로 이동해 후속 작업을 진행합니다:

$ cd mysite

(이제부터는 프로젝트 루트 폴더 mysite에서 명령어를 실행한다고 가정하겠습니다.)

5. Django 앱(App) 생성 및 연결

Django 프로젝트를 만들었으니, 그 안에 **앱(app)**을 생성해보겠습니다. 앱은 Django 프로젝트 내에서 특정 기능을 수행하는 모듈化된 구성요소라고 생각할 수 있습니다. 예를 들어 블로그 프로젝트라면 게시판 앱, 계정 관리 앱 등을 각각 만들 수 있습니다. 우리 튜토리얼에서는 간단히 하나의 앱을 만들어볼 것입니다.

프로젝트 폴더(manage.py 파일이 있는 위치)에서 다음 명령을 실행하세요:

(venv) $ python manage.py startapp myapp

명령을 실행하면 myapp이라는 새 폴더가 생성됩니다. 이것이 우리가 방금 만든 Django 앱입니다. myapp 폴더의 구조는 다음과 같습니다:

myapp/
    __init__.py   # 앱 패키지 초기화 파일
    admin.py      # 관리자 사이트 설정
    apps.py       # 앱 구성 클래스
    migrations/   # 마이그레이션 파일 저장 폴더 (DB 변경 관리)
        __init__.py
    models.py     # 데이터베이스 모델 정의
    tests.py      # 테스트 코드
    views.py      # 뷰 함수 정의

여기서 우리가 주로 다룰 파일은 views.py입니다. (간단한 웹 페이지 출력 기능을 이곳에 작성할 것입니다.)
앱을 생성했지만, 아직 Django에게 이 앱을 사용한다고 알려주지 않았습니다. Django 프로젝트에 새로운 앱을 추가할 때는 설정에 앱을 등록해야 합니다. mysite/settings.py 파일을 열어보면 INSTALLED_APPS 항목이 있을 것입니다. 이 리스트에 'myapp'을 추가해 주세요. 설정 파일의 해당 부분은 예를 들어 이렇게 바뀝니다:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'myapp',  # 새로 생성한 앱 등록
]

위와 같이 'myapp' 문자열을 추가했다면, Django가 우리의 앱을 인식하게 됩니다. (앱 이름은 startapp 때 사용한 이름과 동일해야 합니다.) 만약 앱을 등록하지 않으면 나중에 데이터베이스 마이그레이션 등을 할 때 Django가 해당 앱을 무시하게 되므로, 새로운 앱을 만들 때는 이 단계를 꼭 챙기세요.

6. 간단한 페이지 뷰와 URL 연결 (Hello, Django!)

이제 “Hello, Django!”라는 메시지를 웹 페이지로 출력하는 **뷰(view)**를 만들어보고, URL에 연결해보겠습니다. 뷰는 웹 요청(request)을 받아서 사용자에게 응답(response)을 반환하는 함수 또는 클래스를 말합니다. 우리 예제에서는 간단히 함수형 뷰를 하나 만들어보겠습니다.

1. 뷰 함수 작성: myapp/views.py 파일을 열어서 아래 코드를 작성하세요:여기서 hello라는 이름의 함수가 바로 뷰 함수입니다. HttpResponse를 임포트하여 사용했는데, 이것은 주어진 문자열을 HTTP 응답으로 돌려주는 Django 클래스입니다. 결과적으로 사용자가 이 뷰를 요청하면 "Hello, Django!" 라는 내용의 웹 페이지를 받게 될 것입니다.
2. # myapp/views.py from django.http import HttpResponse def hello(request): return HttpResponse("Hello, Django!")
3. URL 설정: 방금 만든 뷰를 웹에서 접근하려면 URL에 연결해야 합니다. mysite/urls.py (프로젝트의 URL 설정 파일)을 열어, 기본 내용에 우리의 앱 뷰를 포함시키도록 수정합니다. 기본적으로 urls.py에는 관리자 사이트를 위한 admin/ 경로가 들어있는데, 여기에 새로운 URL 패턴을 추가하겠습니다.
   • 우선 파일 상단에 우리의 앱의 뷰를 임포트합니다:
   • from myapp import views # myapp의 views 모듈 임포트
   • 그리고 urlpatterns 리스트에 새로운 패턴을 추가합니다:
   • urlpatterns = [ path('hello/', views.hello, name='hello'), # 새로 추가: /hello/ URL은 hello 뷰로 연결 path('admin/', admin.site.urls), ]
   위와 같이 작성하고 저장하세요. 이제 /hello/ 경로로 요청이 오면 views.hello 함수가 실행되어 그 응답으로 "Hello, Django!" 문구를 띄우게 됩니다. (여기서 name='hello' 부분은 URL 패턴에 이름을 부여한 것으로, 나중에 이 이름을 통해 URL을 역으로 찾을 때 유용하지만 지금은 신경 안 쓰셔도 됩니다.)
4. 주의: urlpatterns에 항목을 추가할 때 문법에 맞게 쉼표(,)를 넣는 것을 잊지 마세요. 또한 from django.urls import path와 from myapp import views 등이 파일 상단에 이미 또는 새로 포함되어야 합니다. 만약 이 부분이 빠지면 서버 실행 시 오류가 발생할 수 있습니다.

7. 개발 서버 실행과 테스트 방법

모든 준비는 끝났습니다. 이제 Django의 **개발 서버(development server)**를 실행하여 우리가 만든 페이지를 확인해보겠습니다. 터미널에서 (가상환경이 활성화된 상태로) 아래 명령을 실행하세요:

(venv) $ python manage.py runserver

명령을 실행하면 서버가 실행되고 터미널에 로그가 출력됩니다. 정상적으로 실행되었다면 다음과 같은 메시지가 보입니다:

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
May 14, 2025 - 11:30:00
Django 5.2.1, using settings 'mysite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

위와 같은 로그에서 Starting development server at http://127.0.0.1:8000/ 라는 줄을 찾을 수 있을 것입니다. 이 주소가 바로 로컬 개발 서버 주소입니다. 웹 브라우저를 열고 http://127.0.0.1:8000/hello/ 에 접속해보세요. 우리가 설정한 /hello/ URL에 대응하는 뷰가 실행되어, 브라우저 화면에 "Hello, Django!" 라는 문구가 나타나는 것을 볼 수 있습니다!

잘 작동한다면, 여러분은 Django에서 첫 번째 페이지를 성공적으로 띄운 것입니다 🎉. 혹시 http://127.0.0.1:8000/ (슬래시로 끝나는 루트 경로)로 들어갔는데 다른 화면이 보인다면 놀라지 마세요. Django가 기본적으로 제공하는 환영 페이지일 가능성이 큽니다. 우리는 /hello/ 경로만 따로 만들었기 때문에, 반드시 URL에 /hello/를 포함해서 접속해야 우리의 뷰가 나타납니다. 주소를 정확히 입력했는데도 페이지가 안 뜬다면, 터미널에 에러 메시지가 없는지 확인해보세요. 오타나 누락된 설정이 있으면 Django가 상세한 오류 메시지를 터미널과 웹 페이지에 표시해 줍니다.

개발 서버는 실행된 터미널을 차지하고 계속 동작 중이므로, 서버를 중지하려면 터미널 창에서 Ctrl+C (맥에서는 Control+C)를 눌러주세요. 서버가 종료되면 커서 입력 상태로 돌아옵니다.

---

이제 Python과 Django를 이용한 개발 환경 구축부터 간단한 웹 페이지 출력까지의 기본 여정을 마쳤습니다. 정리하자면, Python 설치 → 가상환경 설정 → Django 설치 → 프로젝트 생성 → 앱 생성 → 뷰와 URL 연결 → 개발 서버 실행의 단계로 진행했습니다. 처음에는 생소한 용어와 구조가 많았겠지만, 한 단계씩 따라오면서 Django 프로젝트의 큰 그림을 보셨을 것입니다. 😀

이 튜토리얼의 예제는 매우 기본적인 것이지만, 이를 기반으로 앞으로 장고로 할 수 있는 일들은 무궁무진합니다. 이제 “Hello, Django!”를 발판삼아, 모델을 추가하여 데이터를 다루거나 더 많은 뷰와 URL을 만들어보는 등 다음 단계를 차근차근 밟아보세요. Django 공식 문서와 커뮤니티에도 유용한 자료가 많으니 참고하면서 연습하면 금방 익숙해질 것입니다.