개발 환경 준비와 첫 Flask 앱 실행하기

2026-09-09Views 12약 7분생성형 AI 활용

Summary

이번 장에서 만들 것

이번 장에서는 Flask 프로젝트의 출발점을 만든다. 목표는 크지 않다. 파이썬이 제대로 설치되어 있는지 확인하고, 프로젝트 폴더를 만들고, 가상환경을 준비한 뒤, Flask를 설치한다. 마지막으로 브라우저에서 Hello, Flask!라는 문장을 확인한다.

가상환경은 프로젝트마다 따로 마련하는 작은 작업실이라고 생각하면 된다. 한 컴퓨터에 여러 파이썬 프로젝트가 있을 때, 각 프로젝트가 필요한 도구와 버전이 서로 섞이지 않게 막아 준다. Flask 공식 문서도 프로젝트별 의존성을 분리하기 위해 가상환경 사용을 권장한다.¹

개발 환경 준비와 첫 Flask 앱 실행하기 AI 생성 이미지

파이썬 버전 확인하기

먼저 터미널을 연다. Windows에서는 PowerShell 또는 명령 프롬프트를 사용할 수 있고, macOS와 Linux에서는 터미널 앱을 사용하면 된다.

다음 명령어를 입력한다.

python --version

만약 위 명령어가 동작하지 않으면 운영체제에 따라 다음 명령어를 시도한다.

python3 --version

Windows에서는 아래 명령어가 동작할 수도 있다.

py --version

Flask 3.x는 Python 3.9 이상을 지원한다.¹ 이 책을 따라 한다면 가능하면 Python 3.10 이상을 사용하는 편이 좋다. 버전이 너무 낮다면 먼저 파이썬을 새로 설치하자.

pip도 확인한다. pip는 파이썬 패키지를 설치하는 도구다. 스마트폰의 앱 스토어처럼, 필요한 라이브러리를 내려받아 프로젝트에 추가해 준다.

python -m pip --version

python -m pip 형태를 쓰면 현재 선택된 파이썬에 연결된 pip를 실행한다. 초보자에게는 이 방식이 더 안전하다. 나중에 가상환경을 사용할 때도 "지금 프로젝트의 파이썬에 Flask를 설치한다"는 뜻이 분명해진다.

프로젝트 폴더 만들기

이제 실습용 폴더를 만든다. 이 책에서는 프로젝트 이름을 flask-study로 사용하겠다.

mkdir flask-study
cd flask-study

폴더 이름은 자유롭게 정해도 된다. 다만 한글, 공백, 특수문자가 들어간 이름은 처음에는 피하는 것이 좋다. 경로 문제로 불필요한 오류를 만날 수 있기 때문이다.

현재 위치가 프로젝트 폴더인지 확인하려면 다음 명령어를 사용한다.

pwd

Windows 명령 프롬프트에서는 아래 명령어를 사용할 수 있다.

cd

프로젝트 폴더는 앞으로 예제 파일이 쌓이는 공간이다. 지금은 비어 있어도 괜찮다.

가상환경 만들고 활성화하기

프로젝트 폴더 안에서 가상환경을 만든다. 폴더 이름은 보통 .venv를 많이 쓴다.

python -m venv .venv

만약 python 명령어가 동작하지 않는 환경이라면 다음처럼 입력한다.

python3 -m venv .venv

Windows에서 py 명령어를 쓴다면 다음도 가능하다.

py -m venv .venv

명령이 끝나면 .venv라는 폴더가 생긴다. 이 안에 이 프로젝트 전용 파이썬과 패키지 저장 공간이 만들어진다. 이 폴더는 직접 수정하지 않는다.

이제 가상환경을 활성화한다. 활성화는 "이 터미널에서는 앞으로 이 프로젝트의 파이썬을 쓰겠다"고 알려 주는 과정이다.

macOS 또는 Linux:

source .venv/bin/activate

Windows PowerShell:

.venvScriptsActivate.ps1

Windows 명령 프롬프트:

.venvScriptsactivate.bat

성공하면 터미널 앞쪽에 (.venv)가 보이는 경우가 많다. 예를 들면 다음과 같다.

(.venv) flask-study $

VS Code를 사용한다면 프로젝트 폴더를 연 뒤 터미널을 새로 만들었을 때 .venv가 자동으로 선택될 수 있다. 그래도 Flask가 설치되지 않았다는 오류가 나면, 먼저 터미널 앞에 (.venv)가 보이는지 확인하자.²

Flask 설치하기

가상환경이 활성화된 상태에서 Flask를 설치한다.

python -m pip install Flask

여기서 Flask의 대소문자는 크게 문제 되지 않지만, 공식 패키지 이름에 맞춰 적는 습관을 들이면 좋다.

설치가 끝났는지 확인한다.

python -m pip show Flask

정상이라면 Name, Version, Location 같은 정보가 출력된다. 여기서 Location 경로 안에 현재 프로젝트의 .venv가 들어 있다면 올바른 가상환경에 설치된 것이다.

설치된 패키지 목록을 간단히 보고 싶다면 다음 명령어도 사용할 수 있다.

python -m pip list

이제 Flask를 사용할 준비가 끝났다.

가장 작은 Flask 앱 작성하기

프로젝트 폴더 안에 app.py 파일을 만든다. 파일 구조는 지금 이렇게 된다.

flask-study/
├─ .venv/
└─ app.py

app.py에 다음 코드를 입력한다.

from flask import Flask

app = Flask(__name__)

@app.route("/")
def home():
    return "Hello, Flask!"

한 줄씩 살펴보자.

from flask import Flask는 Flask 클래스를 가져온다. 클래스는 웹 애플리케이션을 만들기 위한 설계도라고 생각하면 된다.

app = Flask(__name__)는 실제 Flask 애플리케이션 객체를 만든다. 여기서 app은 앞으로 요청을 받고 응답을 돌려주는 중심 역할을 한다.

@app.route("/")는 URL과 함수를 연결한다. /는 사이트의 첫 화면 주소다. 브라우저가 http://127.0.0.1:5000/로 요청을 보내면 바로 아래의 home() 함수가 실행된다.

def home():은 파이썬 함수다. 함수 이름은 꼭 home일 필요는 없지만, 어떤 화면을 담당하는지 알 수 있게 짓는 편이 좋다.

return "Hello, Flask!"는 브라우저에 돌려줄 응답이다. 지금은 단순한 문자열이지만, 뒤 장에서는 HTML 파일과 JSON 응답도 다룬다.

로컬 서버 실행하기

이제 Flask 개발 서버를 실행한다. 개발 서버는 내 컴퓨터 안에서만 실습용으로 띄우는 작은 서버다. 실제 서비스 배포용 서버와는 다르다.

flask --app app run

정상적으로 실행되면 다음과 비슷한 메시지가 보인다.³

 * Serving Flask app 'app'
 * Running on http://127.0.0.1:5000

브라우저를 열고 아래 주소로 접속한다.

http://127.0.0.1:5000/

화면에 Hello, Flask!가 보이면 성공이다.

여기서 127.0.0.1은 내 컴퓨터 자신을 가리키는 주소다. localhost라고 써도 대부분 같은 의미로 동작한다. 5000은 포트 번호다. 포트는 한 컴퓨터 안에서 여러 프로그램이 네트워크 요청을 나누어 받기 위한 번호표라고 생각하면 된다.

서버를 멈추려면 터미널에서 다음 키를 누른다.

Ctrl + C

서버가 실행 중인 터미널은 명령어를 입력하는 곳이 아니라 서버 로그를 보여 주는 곳이 된다. 새 명령을 입력하려면 서버를 멈추거나 터미널을 하나 더 열면 된다.

디버그 모드로 실행하기

개발 중에는 코드를 자주 고친다. 그때마다 서버를 껐다 켜면 번거롭다. Flask의 디버그 모드를 사용하면 코드가 바뀌었을 때 개발 서버가 자동으로 다시 시작된다. 또한 요청 처리 중 오류가 발생하면 브라우저와 터미널에 더 자세한 정보를 보여 준다.³

다음 명령어로 실행한다.

flask --app app run --debug

이제 app.py의 응답 문장을 바꿔 보자.

return "Hello, Flask Debug Mode!"

파일을 저장한 뒤 브라우저를 새로고침하면 바뀐 문장이 보인다. 이것이 자동 재시작 기능이다. Flask가 파일 변경을 감지하고 개발 서버를 다시 띄운 것이다.

단, 디버그 모드는 개발할 때만 사용해야 한다. 디버그 도구는 오류를 찾는 데 편리하지만, 잘못 노출되면 외부 사람이 서버에서 파이썬 코드를 실행할 위험이 있다. 공식 문서도 운영 환경에서는 개발 서버와 디버거를 사용하지 말라고 경고한다.³

지금은 내 컴퓨터에서 학습하는 단계이므로 괜찮다. 나중에 배포를 다룰 때는 다른 방식으로 실행한다.

자주 만나는 문제 해결하기

처음 환경을 잡을 때는 코드보다 설정에서 더 많이 막힌다. 오류가 나면 당황하지 말고 메시지의 핵심 단어를 찾자.

`ModuleNotFoundError: No module named 'flask'`

Flask가 현재 파이썬 환경에 설치되어 있지 않다는 뜻이다. 대부분 가상환경이 활성화되지 않았거나, 다른 파이썬에 Flask를 설치한 경우다.

먼저 (.venv)가 보이는지 확인한다. 보이지 않으면 가상환경을 다시 활성화한다. 그리고 설치 명령을 다시 실행한다.

python -m pip install Flask

설치 위치도 확인한다.

python -m pip show Flask

Location에 프로젝트의 .venv 경로가 포함되어 있어야 한다.

`Address already in use` 또는 포트 충돌

이미 다른 프로그램이 5000번 포트를 사용 중이라는 뜻이다. 이전에 실행한 Flask 서버가 아직 켜져 있을 수도 있다.

먼저 실행 중인 터미널에서 Ctrl + C를 눌러 서버를 멈춘다. 그래도 해결되지 않으면 다른 포트로 실행한다.

flask --app app run --port 5001

그다음 브라우저에서 아래 주소로 접속한다.

http://127.0.0.1:5001/

`flask` 명령어를 찾을 수 없음

가상환경이 활성화되지 않았거나 Flask 설치가 끝나지 않았을 가능성이 크다. 다음 명령으로 실행해 볼 수 있다.

python -m flask --app app run

python -m flask는 현재 파이썬 환경 안의 Flask를 직접 실행하는 방식이다. 초보자에게는 문제를 줄이는 좋은 대안이다.

PowerShell에서 실행 정책 오류가 날 때

Windows PowerShell에서 .venvScriptsActivate.ps1 실행이 막힐 수 있다. 이때는 우선 명령 프롬프트에서 아래 명령을 사용해도 된다.

.venvScriptsactivate.bat

초반에는 환경 문제를 오래 붙잡고 있기보다, 동작하는 터미널로 실습을 이어 가는 것이 좋다.

이번 장에서 확인할 것

이번 장의 핵심은 "처음 한 번 환경을 제대로 잡아 두면 이후 예제를 막힘없이 따라갈 수 있다"는 점이다. 다음 항목이 모두 된다면 준비가 끝났다.

python --version으로 파이썬 버전을 확인할 수 있다.
프로젝트 폴더 안에 .venv 가상환경을 만들었다.
가상환경을 활성화하면 터미널에 (.venv)가 보인다.
python -m pip install Flask로 Flask를 설치했다.
app.py에 최소 Flask 코드를 작성했다.
flask --app app run --debug로 서버를 실행했다.
브라우저에서 http://127.0.0.1:5000/에 접속해 응답을 확인했다.

다음 장에서는 @app.route()를 더 자세히 다룬다. 여러 URL을 만들고, 각각 다른 파이썬 함수에 연결해 보면서 웹 애플리케이션의 길을 넓혀 갈 것이다.

참고

¹Flask Installation 문서

²Visual Studio Code Flask Tutorial

³Flask Quickstart 문서

책 목록

초보자를 위한 파이썬 Flask 학습

전체 목차 보기