Python tomllib 사용법

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

Python tomllib 사용법

Python에서 pyproject.toml이나 별도 설정 파일을 읽어야 할 때는 표준 라이브러리 tomllib가 가장 먼저 검토할 도구다. tomllib는 Python 3.11부터 추가됐고, 현재 Python 3.14 문서도 이 모듈을 TOML 파서로 설명한다.

핵심은 세 가지다. tomllib는 읽기 전용이고, 파일 입력은 바이너리 모드가 기준이며, 부동소수점 변환은 parse_float로 바꿀 수 있다. 이 글은 Python 공식 문서, PEP 680, PyPA의 pyproject.toml 설명을 바탕으로 실무에서 바로 판단할 기준만 정리한다.

Python tomllib는 무엇을 위한 모듈일까?

tomllib는 TOML 문서를 Python 객체로 파싱하는 표준 라이브러리다. Python 3.14 문서는 변환 결과가 딕셔너리, 리스트, 문자열, 정수, 날짜/시간 객체 등으로 매핑된다고 설명한다.

도입 배경은 PEP 680에 정리돼 있다. Python 생태계에서 pyproject.toml 사용이 늘어나면서, 별도 의존성 없이 TOML을 읽을 수 있는 표준 도구가 필요해졌고 그 결과가 tomllib다.

언제 tomllib를 쓰면 될까?

다음 조건이면 tomllib가 기본값으로 무난하다.

• 실행 환경이 Python 3.11 이상이다.
• TOML 파일을 읽기만 하면 된다.
• pyproject.toml처럼 표준 형식의 설정 파일을 안전하게 파싱하고 싶다.
• 서드파티 TOML 파서를 추가 설치하지 않고 싶다.

반대로 TOML을 다시 저장하거나 수정 결과를 파일에 써야 하면 tomllib만으로는 부족하다. Python 공식 문서는 쓰기 작업용 모듈을 제공하지 않으며, 이 경우에는 별도 라이브러리를 검토해야 한다.

기본 사용법은 어떻게 될까?

가장 기본 형태는 파일을 바이너리 모드로 열고 tomllib.load()를 호출하는 방식이다. 문서는 fp가 읽기 가능한 바이너리 파일 객체여야 한다고 적고 있다.

import tomllib

with open("pyproject.toml", "rb") as f:
    data = tomllib.load(f)

project_name = data["project"]["name"]

문자열이 이미 메모리에 있다면 tomllib.loads()를 쓸 수 있다. 이 함수는 TOML 문서 문자열을 직접 받아 같은 형태의 Python 객체를 돌려준다.

import tomllib

text = """
[project]
name = "sample-app"
version = "1.0.0"
"""

data = tomllib.loads(text)
print(data["project"]["version"])

왜 파일을 텍스트 모드가 아니라 바이너리 모드로 열어야 할까?

공식 문서는 tomllib.load()의 입력을 바이너리 파일 객체로 정의한다. 이는 TOML 명세가 UTF-8 인코딩을 기준으로 하기 때문이며, 파일 읽기 단계에서 플랫폼 기본 인코딩이나 줄바꿈 처리 차이를 끼워 넣지 않는 쪽이 더 명확하다.

실무에서는 open(path, "rb")를 기본 패턴으로 고정하는 편이 안전하다. 반대로 이미 문자열로 읽어 둔 데이터라면 그때는 loads()를 사용하면 된다.

parse_float는 언제 필요할까?

TOML 안의 부동소수점 값을 기본 float 대신 다른 타입으로 받고 싶다면 parse_float 인자를 사용할 수 있다. Python 문서는 이 인자가 문자열을 받아 다른 객체를 반환하는 호출 가능 객체여야 한다고 설명한다.

from decimal import Decimal
import tomllib

with open("settings.toml", "rb") as f:
    data = tomllib.load(f, parse_float=Decimal)

price = data["payment"]["amount"]

예를 들어 금액이나 정밀한 소수 계산을 다뤄야 하면 Decimal로 받는 편이 더 예측 가능하다. 다만 이 선택은 TOML 파싱 자체를 바꾸는 것이 아니라, 부동소수점 토큰이 Python 객체로 변환되는 방식을 바꾸는 것이다.

 

 

pyproject.toml을 읽을 때 무엇을 조심해야 할까?

PyPA 문서는 pyproject.toml이 빌드 시스템과 프로젝트 메타데이터를 담는 표준 파일이라고 설명한다. 따라서 tomllib로 읽은 뒤에는 단순히 키가 존재하는지만 보는 것이 아니라, 어느 테이블이 어떤 표준을 따르는지 구분해서 해석해야 한다.

대표적으로 [build-system]과 [project]는 의미가 다르다. [project] 메타데이터는 PEP 621 규칙을 따르며, 도구별 설정은 보통 [tool.도구이름] 아래에 들어간다.

import tomllib

with open("pyproject.toml", "rb") as f:
    data = tomllib.load(f)

project = data.get("project", {})
requires_python = project.get("requires-python")
dependencies = project.get("dependencies", [])

즉 tomllib는 파싱까지만 책임지고, 어떤 키 조합이 유효한지는 해당 표준이나 도구 문서를 따로 봐야 한다. 이 점을 구분해야 "파싱 성공"과 "메타데이터가 표준에 맞음"을 혼동하지 않는다.

에러 처리는 어떻게 보면 될까?

문법이 잘못된 TOML을 읽으면 tomllib.TOMLDecodeError가 발생한다. Python 3.14 문서는 이 예외가 msg, doc, pos, lineno, colno 같은 속성을 제공한다고 설명한다.

import tomllib

try:
    with open("broken.toml", "rb") as f:
        data = tomllib.load(f)
except tomllib.TOMLDecodeError as exc:
    print(exc.msg)
    print(exc.lineno, exc.colno)

또한 Python 3.14 문서는 이 예외를 위치 인자로 생성하는 방식이 deprecated라고 명시한다. 직접 예외를 만들어 던질 일이 거의 없더라도, 예외 객체 구조가 문서화되어 있다는 점은 로그와 진단 메시지를 만들 때 유용하다.

실무 기준으로 정리하면?

대부분의 Python 3.11 이상 프로젝트에서는 TOML 읽기 기본값으로 tomllib를 써도 된다. 표준 라이브러리라 의존성 추가가 없고, pyproject.toml 같은 표준 파일을 읽는 목적에 잘 맞기 때문이다.

다만 아래는 분리해서 판단해야 한다.

• 파일을 수정해 다시 저장해야 하는가
• 파싱 이후 메타데이터 유효성 검증까지 필요한가
• 실행 환경이 Python 3.11 미만인가

이 세 조건 중 하나라도 걸리면 tomllib만으로는 부족할 수 있다. 반대로 "읽기만 하고, Python 3.11 이상이며, 표준 라이브러리를 선호한다"면 선택은 단순하다.

FAQ

Python 3.10 이하에서는 tomllib를 쓸 수 없을까?

표준 라이브러리 tomllib는 Python 3.11에서 추가됐다. 따라서 3.10 이하에서는 같은 이름의 표준 모듈을 사용할 수 없다.

tomllib로 TOML 파일을 다시 저장할 수 있을까?

아니다. Python 3.14 문서는 tomllib를 파싱 모듈로 설명하며, 쓰기 API는 제공하지 않는다. 읽기와 쓰기가 모두 필요하면 별도 라이브러리를 따로 검토해야 한다.

pyproject.toml을 읽었다면 그 내용이 표준에 맞는지도 자동으로 보장될까?

그렇지 않다. tomllib는 TOML 문법을 Python 객체로 바꿔 줄 뿐이고, [project]나 [build-system]의 의미 검증은 해당 표준과 도구 규칙이 맡는다.

참고 자료

• Python 3.14 tomllib 문서
• PEP 680 - tomllib: Support for Parsing TOML in the Standard Library
• PyPA - Writing your pyproject.toml
• PyPA - pyproject.toml specification
• TOML v1.0.0 specification