10.Python config.json 파일 읽고 저장하는 방법 — 설정 파일 관리 완벽 가이드

 저도 처음엔 데이터베이스 주소나 결과물 저장 경로를 소스 코드 상단에 변수로 적어두고 썼습니다. 개발할 때는 로컬 경로로 바꿨다가, 서버에 올릴 때는 다시 운영 서버 경로로 바꾸는 작업을 매번 수동으로 진행했죠. 그러다 어느 날 단 하나의 경로를 미처 고치지 않고 배포하는 바람에, 실제 운영 데이터가 로컬 테스트 데이터에 덮어써 지는 대형 사고를 쳤습니다. 수습하느라 주말 16시간을 통째로 날린 뒤, 설정값은 무조건 코드와 분리해야 한다는 걸 깨닫고 config.json을 도입했습니다.

 


Python 프로젝트에서 config.json 파일을 활용한 설정 관리는 코드의 유연성과 유지보수성을 크게 향상시킵니다. 이 글에서는 JSON 파일로 설정을 읽고 저장하는 기본부터, 중첩 구조 처리, 기본값 관리, 그리고 .env 파일과의 역할 분리까지 — VS Code 환경에서 실무에 바로 쓸 수 있는 수준으로 안내해 드리겠습니다.

config.json이 필요한 이유 — 코드와 설정을 분리하는 것

설정값을 코드에 직접 넣으면 생기는 문제

프로그램을 개발하다 보면 자주 바뀌는 값들이 생깁니다. API 서버 주소, 최대 요청 횟수, 파일 저장 경로, 알림 조건 수치 같은 것들입니다. 이 값들을 코드 안에 직접 넣으면 값 하나를 바꿀 때마다 코드를 열고, 수정하고, 저장하고, 다시 실행해야 합니다.

이를 레스토랑에 비유하면 이렇습니다. 메뉴판(config.json)은 따로 있고, 요리사(코드)는 메뉴판을 보고 요리합니다. 메뉴를 바꿀 때 요리사의 머릿속(코드)을 바꾸는 것이 아니라 메뉴판(설정 파일)만 바꾸면 됩니다. 코드는 건드리지 않아도 프로그램의 동작이 달라집니다.

.env 파일과 config.json의 역할 차이

두 파일을 함께 쓰는 경우가 많아 혼동하기 쉽습니다. 역할은 명확히 다릅니다.

구분 .env 파일 config.json
용도 비밀 정보 (API Key, 비밀번호) 일반 설정값 (경로, 수치, 옵션)
깃허브 공개 ❌ 절대 불가 ✅ 공개 가능
형식 KEY=VALUE JSON 구조체
팀 공유 .env.example로 간접 공유 파일 그대로 공유

비밀이 필요 없는 설정값은 config.json으로, API Key처럼 외부에 노출되면 안 되는 값은 .env로 관리하는 것이 원칙입니다.

config.json 파일 기본 구조 만들기

파일 생성 및 구조 설계

VS Code에서 프로젝트 루트 폴더에 config.json 파일을 새로 만들고 아래처럼 작성합니다.

{
  "app": {
    "name": "MyProject",
    "version": "1.0.0",
    "debug": false
  },
  "api": {
    "base_url": "https://api.example.com",
    "timeout": 30,
    "max_retries": 3
  },
  "paths": {
    "output_dir": "./output",
    "log_dir": "./logs",
    "data_dir": "./data"
  },
  "alert": {
    "price_change_threshold": 5.0,
    "volume_multiplier": 3.0,
    "cooldown_minutes": 60
  }
}


JSON은 계층 구조를 그대로 시각화할 수 있어 설정값이 많아져도 분류가 명확합니다. 마치 서랍장에 칸을 나눠 물건을 정리하는 것처럼, 관련 있는 설정끼리 묶어두면 나중에 찾기 쉽습니다.

Python에서 config.json 읽기

기본 읽기 — json 모듈 활용

Python 기본 라이브러리인 json 모듈만으로 충분합니다. 별도 설치가 필요 없습니다.

import json
import os
from pathlib import Path

def load_config(config_path: str = "config.json") -> dict:
    """config.json 파일을 읽어 딕셔너리로 반환합니다."""

    # 스크립트 파일 기준으로 경로 설정 (경로 오류 방지)
    base_dir = Path(__file__).parent
    full_path = base_dir / config_path

    if not full_path.exists():
        raise FileNotFoundError(
            f"설정 파일을 찾을 수 없습니다: {full_path}\n"
            f"프로젝트 루트에 config.json 파일을 생성해 주세요."
        )

    with open(full_path, "r", encoding="utf-8") as f:
        config = json.load(f)

    print(f"✅ 설정 파일 로드 완료: {full_path}")
    return config


# 사용 예시
config = load_config()

# 중첩 구조 접근
app_name = config["app"]["name"]
timeout = config["api"]["timeout"]
output_dir = config["paths"]["output_dir"]

print(f"앱 이름: {app_name}")
print(f"타임아웃: {timeout}초")
print(f"출력 경로: {output_dir}")


.get()으로 안전하게 읽기 — KeyError 방지

딕셔너리에서 존재하지 않는 키를 접근하면 KeyError가 발생합니다. .get() 메서드를 사용하면 키가 없을 때 기본값을 반환해 프로그램이 멈추는 것을 방지합니다.

config = load_config()

# 키가 없으면 오류 발생 — 위험한 방식
# timeout = config["api"]["timeout"]

# 키가 없으면 기본값 반환 — 안전한 방식
timeout = config.get("api", {}).get("timeout", 30)
debug = config.get("app", {}).get("debug", False)
threshold = config.get("alert", {}).get("price_change_threshold", 3.0)

print(f"타임아웃: {timeout}초")
print(f"디버그 모드: {debug}")
print(f"가격 변동 임계값: {threshold}%")

Python에서 config.json 저장하기

설정값을 사용자가 변경하거나, 프로그램 실행 중에 상태를 저장해야 할 때 JSON 파일에 다시 쓸 수 있습니다.

기본 저장

import json
from pathlib import Path

def save_config(config: dict, config_path: str = "config.json") -> None:
    """딕셔너리를 config.json 파일로 저장합니다."""

    base_dir = Path(__file__).parent
    full_path = base_dir / config_path

    with open(full_path, "w", encoding="utf-8") as f:
        json.dump(config, f, ensure_ascii=False, indent=2)

    print(f"✅ 설정 파일 저장 완료: {full_path}")


# 사용 예시 — 특정 값만 변경 후 저장
config = load_config()
config["alert"]["price_change_threshold"] = 7.0  # 임계값 변경
config["app"]["version"] = "1.1.0"               # 버전 업데이트

save_config(config)

💡 ensure_ascii=False: 한글이 포함된 경우 이 옵션 없이 저장하면 \uD55C\uAE00 같은 유니코드 이스케이프로 저장됩니다. 한글을 그대로 저장하려면 반드시 ensure_ascii=False를 추가하십시오.

💡 indent=2: 이 옵션을 주면 들여쓰기가 적용된 읽기 좋은 형태로 저장됩니다. 없으면 한 줄로 압축되어 저장됩니다.



실전 패턴 — ConfigManager 클래스로 통합 관리하기

읽기와 쓰기를 매번 따로 호출하는 대신, 클래스로 묶어두면 프로젝트 어디서든 일관되게 사용할 수 있습니다.

import json
from pathlib import Path
from typing import Any


class ConfigManager:
    """config.json 파일을 읽고 쓰는 기능을 통합 관리하는 클래스입니다."""

    def __init__(self, config_path: str = "config.json"):
        self.config_path = Path(__file__).parent / config_path
        self._config = self._load()

    def _load(self) -> dict:
        """파일에서 설정을 읽어옵니다. 파일이 없으면 빈 딕셔너리를 반환합니다."""
        if not self.config_path.exists():
            print(f"⚠️ 설정 파일 없음. 기본값으로 시작합니다: {self.config_path}")
            return {}

        with open(self.config_path, "r", encoding="utf-8") as f:
            return json.load(f)

    def save(self) -> None:
        """현재 설정을 파일로 저장합니다."""
        with open(self.config_path, "w", encoding="utf-8") as f:
            json.dump(self._config, f, ensure_ascii=False, indent=2)
        print(f"✅ 설정 저장 완료")

    def get(self, *keys: str, default: Any = None) -> Any:
        """중첩 키를 순서대로 전달해 값을 가져옵니다."""
        value = self._config
        for key in keys:
            if not isinstance(value, dict):
                return default
            value = value.get(key, default)
            if value is default:
                return default
        return value

    def set(self, *keys: str, value: Any) -> None:
        """중첩 키를 순서대로 전달해 값을 설정합니다."""
        target = self._config
        for key in keys[:-1]:
            target = target.setdefault(key, {})
        target[keys[-1]] = value

    def reload(self) -> None:
        """파일에서 설정을 다시 읽어옵니다."""
        self._config = self._load()
        print("🔄 설정 파일 다시 로드 완료")


# 실제 사용 예시
cfg = ConfigManager()

# 값 읽기
timeout = cfg.get("api", "timeout", default=30)
threshold = cfg.get("alert", "price_change_threshold", default=5.0)

print(f"타임아웃: {timeout}초")
print(f"임계값: {threshold}%")

# 값 변경 및 저장
cfg.set("alert", "price_change_threshold", value=7.5)
cfg.set("app", "version", value="1.2.0")
cfg.save()


기본값(default config) 안전하게 관리하기

설정 파일이 없거나 특정 키가 빠진 경우를 대비해 기본값을 코드에 정의해 두는 패턴입니다.

import json
from pathlib import Path

# 기본값 정의 — 설정 파일이 없거나 키가 빠진 경우 사용
DEFAULT_CONFIG = {
    "app": {
        "name": "MyProject",
        "version": "1.0.0",
        "debug": False
    },
    "api": {
        "base_url": "https://api.example.com",
        "timeout": 30,
        "max_retries": 3
    },
    "alert": {
        "price_change_threshold": 5.0,
        "cooldown_minutes": 60
    }
}

def load_config_with_defaults(config_path: str = "config.json") -> dict:
    """설정 파일을 읽고, 없는 키는 기본값으로 채웁니다."""

    config = DEFAULT_CONFIG.copy()

    path = Path(__file__).parent / config_path
    if path.exists():
        with open(path, "r", encoding="utf-8") as f:
            user_config = json.load(f)

        # 사용자 설정으로 기본값을 덮어씁니다 (중첩 딕셔너리 병합)
        for section, values in user_config.items():
            if section in config and isinstance(values, dict):
                config[section].update(values)
            else:
                config[section] = values

    return config

자주 발생하는 오류와 해결법

오류 1 — json.decoder.JSONDecodeError 발생

원인: JSON 문법 오류 (쉼표 누락, 따옴표 불일치, 주석 포함 등) 해결: VS Code에서 JSON 파일을 열면 문법 오류 위치를 빨간 밑줄로 표시해 줍니다. 주석(//)은 JSON 표준에서 지원되지 않으므로 제거하십시오.

# 오류 위치 파악을 위한 예외 처리
try:
    with open("config.json", "r", encoding="utf-8") as f:
        config = json.load(f)
except json.JSONDecodeError as e:
    print(f"JSON 문법 오류: {e.msg}")
    print(f"오류 위치: {e.lineno}번째 줄, {e.colno}번째 열")

오류 2 — 한글이 \uXXXX 형태로 저장되는 경우

원인: ensure_ascii=True (기본값)로 저장된 경우 해결: 저장 시 ensure_ascii=False 추가

오류 3 — FileNotFoundError — 파일을 찾을 수 없는 경우

원인: 작업 디렉토리와 파일 위치 불일치 해결: Path(__file__).parent를 기준으로 절대 경로 사용 (위 예제 코드 참고)

마무리 — 핵심 요약

✅ Python config.json 관리 체크리스트

  1. 비밀값은 .env, 일반 설정값은 config.json 으로 역할 분리
  2. json.load() 로 읽기, json.dump() 로 저장
  3. ensure_ascii=False — 한글 깨짐 방지 필수 옵션
  4. indent=2 — 사람이 읽기 좋은 형태로 저장
  5. .get() 메서드 또는 ConfigManager 클래스 로 안전하게 접근
  6. DEFAULT_CONFIG 로 기본값을 미리 정의해 빠진 키에 대비
  7. Path(__file__).parent 기준으로 경로 설정해 FileNotFoundError 방지

다음으로 알아두면 좋은 것

config.json에 익숙해졌다면, 더 복잡한 설정 관리가 필요한 시점에 YAML 형식(PyYAML 라이브러리)을 검토해 보시길 권장합니다. YAML은 주석을 지원하고 들여쓰기로 계층을 표현해 JSON보다 사람이 읽고 쓰기 편리합니다. 특히 Django, FastAPI 같은 프레임워크 기반 프로젝트에서는 YAML 설정 파일이 자주 활용됩니다.



댓글

댓글 쓰기

이 블로그의 인기 게시물

1.Python 설치부터 실행까지 10분 만에 끝내기 — 초보자도 바로 따라 하는 완벽 가이드

이미지
프로그래밍을 처음 시작하기로 결심한 날, 많은 분들이 유튜브를 켜고 이렇게 검색합니다. "파이썬 설치 방법." 영상을 따라가다 보면 어느 순간 화면 속 강사의 컴퓨터와 내 컴퓨터가 달라지기 시작합니다. "명령어를 찾을 수 없습니다", "PATH가 설정되지 않았습니다" 같은 오류 메시지가 등장하고, 결국 설치도 못 한 채 탭을 닫아버리게 됩니다. 이 글은 바로 그 지점을 해결하기 위해 쓰였습니다. 설치 과정에서 실제로 막히는 이유, 놓치기 쉬운 체크박스 한 칸의 의미, 그리고 첫 코드를 실행하는 순간까지 — 군더더기 없이 안내해 드리겠습니다. 저도 처음 설치때 1시간을 소비 했습니다.이제 해매지 마세요~!!  Python이 실제로 하는 일 — 번역가 비유로 이해하기 Python을 설치하기 전에, Python이 무엇인지 정확히 이해하면 이후 과정이 훨씬 자연스러워집니다. 컴퓨터는 본래 0과 1, 즉 기계어만 이해합니다. 사람이 "파일을 열어줘"라고 말해도 컴퓨터는 알아듣지 못합니다. Python은 바로 이 간극을 메우는 번역가 역할을 합니다. 우리가 사람에게 말하듯 작성한 코드를 컴퓨터가 이해할 수 있는 언어로 변환해 주는 것입니다. 여기서 핵심이 있습니다. 번역가가 없으면 대화가 불가능합니다. Python을 설치한다는 것은 곧 이 번역가를 내 컴퓨터에 고용하는 일입니다. 설치가 완료된 순간부터 여러분의 컴퓨터는 Python이라는 언어를 이해하기 시작합니다. Python을 선택해야 하는 이유 문법이 자연어에 가깝습니다 — if 날씨 == "맑음": 나가기() 처럼, 코드가 한국어 문장 구조와 유사합니다. 범용성이 압도적입니다 — 데이터 분석, 웹 개발, 자동화, AI 모델 구축까지 하나의 언어로 가능합니다. 생태계가 방대합니다 — 전 세계 개발자들이 만든 50만 개 이상의 라이브러리가 무료로 제공됩니다. 취업 시장에서 가장 수요가 높습니다 ...
자세한 내용 보기

30.Python pyautogui로 마우스와 키보드 자동화하기: VSCode 실전 가이드

이미지
 저도 처음에 PATH에서 막혔는데, 매일 반복되는 사내 시스템 클릭 작업을 자동화해보려고 pyautogui 를 설치했지만 VSCode에서 실행할 때마다 "No module named 'pyautogui'"라는 오류만 계속 나왔던 기억이 있습니다. 분명 터미널에서는 설치가 잘 됐다고 나왔는데, 알고 보니 VSCode가 바라보고 있던 Python 인터프리터 경로와 제가 패키지를 설치한 경로가 서로 달랐던 것이 원인이었습니다. 인터프리터를 올바르게 맞춰주고 나서야 마우스가 제 손을 대신해 화면을 클릭하고 키보드를 두드리는 신기한 광경을 볼 수 있었습니다. 이번 글에서는 그때의 시행착오를 바탕으로, VSCode 환경에서 Python pyautogui를 활용해 마우스와 키보드를 자동화하는 방법을 정리해보려 합니다. pyautogui란 무엇인가 마우스와 키보드를 코드로 제어하는 라이브러리 pyautogui 는 Python 코드로 마우스 움직임과 클릭, 키보드 입력을 프로그래밍적으로 제어할 수 있게 해주는 GUI 자동화 라이브러리입니다. 웹 브라우저나 애플리케이션 내부 요소를 직접 다루는 Selenium과 달리, pyautogui는 화면 좌표와 픽셀을 기준으로 동작하기 때문에 특정 프로그램에 국한되지 않고 컴퓨터 화면에서 벌어지는 거의 모든 작업을 자동화할 수 있습니다. 비유하자면 pyautogui는 마치 컴퓨터 앞에 보이지 않는 손 하나를 앉혀두는 것과 같습니다. 이 손은 사람이 시키는 대로 정확한 좌표를 클릭하고, 정해진 문장을 타이핑하며, 화면 속 특정 이미지를 찾아내기까지 하는데, 사람과 다른 점은 지치지 않고 똑같은 작업을 몇 번이고 정확하게 반복한다는 것입니다. pyautogui가 유용한 대표적인 상황 반복적인 클릭 작업이 많은 사내 시스템 업무 자동화 특정 시간마다 실행해야 하는 프로그램 작업 자동화 게임이나 소프트웨어 테스트 시 반복 입력 시뮬레이션 화면 캡처와 이미지 인식을 결합한 자동 작업 흐름 구성 매크로 프로그램을 대...
자세한 내용 보기

29.Python subprocess로 외부 명령어 실행하기: VSCode 실전 활용법

이미지
저도 처음에는 회사에서 매일 반복하던 번거로운 서버 배포 작업을 자동화해 보려고, 파이썬 스크립트 안에 깃( git ) 명령어를 넣어 실행하는 코드를 짰던 것이 시작이었습니다. 분명 내 터미널에 직접 입력할 때는 잘만 되던 명령어가, 파이썬 코드로 실행하니 자꾸 FileNotFoundError 만 뱉어내서 도대체 뭐가 문제인지 몇 시간이나 소스 코드 이 줄 저 줄을 뜯어고치며 밤새 삽질을 했습니다. 알고 보니 코드가 아니라 VS Code가 명령 프로그램의 위치를 찾지 못하는 'PATH 환경변수' 문제였죠. 실행 경로를 명시해 주자마자 스크립트가 배포 작업을 알아서 척척 단 5초 만에 끝내는 걸 보고 , 저는 이 파이썬 자동화의 강력함에 완전히 매료되었습니다. 이번 글에서는 그때의 시행착오를 바탕으로 subprocess 를 활용해 외부 명령어를 안전하게 제어하는 방법을 정리해 보겠습니다. Python 코드 안에서 터미널 명령어를 직접 실행하고 싶었던 적이 있으신가요? 예를 들어 git , ffmpeg , curl 같은 외부 프로그램을 Python 스크립트 안에서 자동으로 호출하고 그 결과를 받아와야 하는 경우가 생각보다 자주 발생합니다. 이럴 때 필요한 것이 바로 subprocess 모듈이며, 이를 활용하면 Python이 마치 터미널을 대신 조작하는 것처럼 외부 프로그램을 자유자재로 실행할 수 있습니다. 이번 글에서는 VSCode 환경에서 Python subprocess를 활용해 외부 명령어를 실행하고 결과를 처리하는 방법을 실전 예제와 함께 정리해보겠습니다. subprocess란 무엇인가 Python에서 외부 프로세스를 실행하는 표준 모듈 subprocess 는 Python 표준 라이브러리에 내장된 모듈로, Python 코드 안에서 운영체제의 명령어나 다른 프로그램을 새로운 프로세스로 실행할 수 있게 해줍니다. 쉽게 말해 여러분이 평소 터미널에 직접 타이핑하던 명령어를, Python 코드가 대신 입력해주고 그 결과까지 받아와주는 것이...
자세한 내용 보기