Django基礎 #2 プロジェクトのセットアップ — uv + django-admin startproject

#1 Django とは で Django がフルスタックという位置を取りました。今回は 空のディレクトリ → 動作する最初のページ までの一息を見ます。ツールは モダン Python 実践 #1 で使ったのと同じ uv で統一します。

事前準備 — Python と uv #

Django 5.x は Python 3.10 以上 を要求します。このシリーズは 3.13 で進めます。uv がすでにあるならスキップ、なければ:

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

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

プロジェクトを作る #

空のディレクトリに uv の仮想環境を作り、Django をインストールします。

mkdir myblog && cd myblog
uv init --python 3.13
uv add django

uv init が作るもの:

• pyproject.toml — プロジェクトのメタデータ、依存関係
• .python-version — 使用する Python バージョン
• .venv/ — 仮想環境 (自動生成、git から除外)

uv add django でインストールされたあとバージョン確認:

uv run django-admin --version
# 5.1.x のような出力

django-admin startproject — プロジェクト骨格の生成 #

Django のすべての CLI エントリーポイントは 2 つです — django-admin (プロジェクトを作る前)、manage.py (作った後)。最初の骨格は django-admin で作ります。

uv run django-admin startproject config .

最後の . が重要です。書かないと config/config/... のように 1 段階深く入ります。. を付けると現在のディレクトリに直接 作成されます。

名前を config にした理由 — mysite、myproject のような名前は意味がなく、設定の集まり という本質を表すほうが良いからです。コミュニティのコンベンションです。

作成された構造 #

myblog/
├── .python-version
├── .venv/
├── pyproject.toml
├── uv.lock
├── manage.py             # Django CLI エントリーポイント (これからすべての命令はこれで)
└── config/
    ├── __init__.py
    ├── settings.py       # すべての設定値
    ├── urls.py           # 最上位の URL ルーティング
    ├── asgi.py           # ASGI エントリーポイント (async、Channels 用)
    └── wsgi.py           # WSGI エントリーポイント (伝統的な同期デプロイ用)

各ファイルの役割:

• manage.py — runserver、migrate、createsuperuser などのすべての命令をこれで
• settings.py — DB、アプリリスト、ミドルウェア、シークレットキーなど
• urls.py — /admin/、/posts/ のような最上位の URL マッピング
• asgi.py / wsgi.py — サーバーのエントリーポイント。開発段階では直接触らない

最初の実行 — runserver #

uv run python manage.py runserver

デフォルトポート 8000 で起動します。ブラウザで http://127.0.0.1:8000 を開くと 「The install worked successfully! Congratulations!」 というロケットページが表示されます。

初回実行時にコンソールに赤い文字で You have N unapplied migrations のような警告が出るかもしれません。次のステップで解決します。

ポート変更: uv run python manage.py runserver 8080 LAN 公開: uv run python manage.py runserver 0.0.0.0:8000

最初のマイグレーション — ビルトインアプリのテーブル #

Django はインストールしてすぐ内部アプリ (auth、sessions、admin、contenttypes、messages、staticfiles) を有効化します。これらのアプリが使うテーブル (auth_user、django_session など) を DB に作る必要があります。

uv run python manage.py migrate

デフォルトの DB は SQLite で、プロジェクトのルートに db.sqlite3 ファイルが自動で作成されます。PostgreSQL や MySQL に変えるのは 中級 #6 で。

マイグレーションが終わると、コンソールに Applying auth.0001_initial... OK のようなログが続けて出力され、もう赤い警告は出なくなります。

最初のアプリ — startapp blog #

Django で app は 再利用可能な機能単位 です。1 つの project の中に複数の app — 例: blog、accounts、payments。

uv run python manage.py startapp blog

作成される構造:

blog/
├── __init__.py
├── admin.py          # Admin 登録 (#7)
├── apps.py           # アプリのメタデータ
├── migrations/
│   └── __init__.py
├── models.py         # モデル定義 (#3)
├── tests.py          # テスト
└── views.py          # ビュー (#4)

(テンプレート / static / urls ディレクトリは自動では作られません — 直接追加します。#4、#5 で。)

INSTALLED_APPS への登録 #

作った app を Django に認識させるには settings.py に登録する必要があります。

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "blog",                         # 追加
]

リストの末尾に "blog" の 1 行。より正確には "blog.apps.BlogConfig" (apps.py のクラス) と書くこともできますが、短く "blog" だけでも動作します。

settings.py の主要設定 #

最初に触ってみる項目たち:

# セキュリティ — 外部に絶対公開禁止
SECRET_KEY = "django-insecure-..."

# デバッグ — 本番では必ず False
DEBUG = True

# DEBUG=False のときどのホストを許可するか
ALLOWED_HOSTS = []

# インストール済みアプリ
INSTALLED_APPS = [...]

# ミドルウェア (リクエスト/レスポンスのパイプライン)
MIDDLEWARE = [...]

# 最上位 URL モジュール
ROOT_URLCONF = "config.urls"

# テンプレート設定
TEMPLATES = [...]

# データベース — デフォルト SQLite
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",
    }
}

# 国際化
LANGUAGE_CODE = "ko-kr"      # デフォルト en-us → 韓国語に
TIME_ZONE = "Asia/Seoul"     # UTC → ソウル
USE_I18N = True
USE_TZ = True                # DB は UTC で保存、表示時に変換

# 静的ファイル (#5)
STATIC_URL = "static/"

DEBUG=True は開発専用です。本番にそのまま上げるとエラーページにコードと環境変数が全部公開されます。本番デプロイは 上級 #7 で扱います。

環境変数の分離 — django-environ #

FastAPI #1 で pydantic-settings でやったのと同じく、Django でも環境変数でシークレットを分離するのが標準です。

uv add django-environ

import environ
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

env = environ.Env(
    DEBUG=(bool, False),
)
environ.Env.read_env(BASE_DIR / ".env")

SECRET_KEY = env("SECRET_KEY")
DEBUG = env("DEBUG")
ALLOWED_HOSTS = env.list("ALLOWED_HOSTS", default=["127.0.0.1", "localhost"])

SECRET_KEY=django-insecure-replace-me-in-production
DEBUG=True
ALLOWED_HOSTS=127.0.0.1,localhost

.gitignore に .env を追加することは必須です。

最初の view を一回 — シリーズの出発点 #

blog/views.py に最も小さい view を 1 行:

from django.http import HttpResponse


def index(request):
    return HttpResponse("Hello, blog!")

blog/urls.py を新しく作ります (Django が自動で作らないと言いましたね)。

from django.urls import path

from . import views

app_name = "blog"

urlpatterns = [
    path("", views.index, name="index"),
]

最上位の config/urls.py で blog の URL を含めます。

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("admin/", admin.site.urls),
    path("blog/", include("blog.urls")),
]

サーバーを再度立ち上げて http://127.0.0.1:8000/blog/ を開くと Hello, blog! が表示されます。

URL / view のより詳しいパターンは #4 で。

よく使う manage.py コマンド #

覚えておくと良いコマンドたち:

uv run python manage.py shell は特によく使います。モデルを import して ORM をすぐに触れます。

まとめ #

今回つかんだもの:

• uv init + uv add django で依存関係の分離
• django-admin startproject config . — プロジェクトの骨格
• manage.py — 以後すべての命令
• runserver — 開発サーバー、自動リロード
• migrate — ビルトインアプリのテーブル生成
• startapp blog — 最初のアプリ生成、INSTALLED_APPS に登録
• settings.py の主要項目 — DEBUG、INSTALLED_APPS、DATABASES、LANGUAGE_CODE、TIME_ZONE
• django-environ でシークレット分離、.env は git 除外
• 最初の view — views.py + アプリ別 urls.py + 最上位の include

次回(#3 Models と ORM 基礎)では blog/models.py に Post モデルを定義し、makemigrations → migrate の流れとともに Django ORM の QuerySet を初めて触ります。