소개
Odoo 매니페스트 오류는 모듈의 __manifest__.py 파일에 문제(문법, 경로, 의존성 표기 등)가 있을 때 발생합니다. 이 파일은 모듈의 이름·버전·의존성·로드할 데이터와 설치 가능 여부 등 핵심 메타데이터를 정의하므로 제대로 작성되지 않으면 Odoo가 모듈을 올바르게 처리할 수 없습니다.
매니페스트 파일에 문제가 있으면 Odoo는 다음과 같은 문제가 발생할 수 있습니다:
- 모듈을 인식하지 못함
- 모듈 설치를 거부함
- 업그레이드 중 실패 발생
- 서버 시작 시 오류 발생
커스텀 모듈 개발이나 버전 마이그레이션 과정에서 매니페스트 관련 오류가 특히 빈번합니다.
이 가이드는 매니페스트 오류의 원인을 파악하고, 단계별로 올바르게 고치는 방법을 설명합니다.
Odoo의 매니페스트 파일이란 무엇인가?
모든 Odoo 모듈에는 반드시 __manifest__.py 파일이 포함됩니다.
예시:
{
'name': 'Custom Sales Extension',
'version': '16.0.1.0.0',
'depends': ['base', 'sale'],
'data': [
'views/sale_order_view.xml',
'security/ir.model.access.csv',
],
'installable': True,
}
이 파일은 Odoo에게 다음을 알려줍니다:
- 모듈의 이름(무엇인지)
- 의존하는 모듈 목록(무엇이 먼저 필요한지)
- 로드해야 할 파일 목록(어떤 자원을 불러올지)
- 설치 가능 여부
여기에서 한 가지라도 잘못되면 모듈이 정상적으로 작동하지 않습니다.
매니페스트 오류가 자주 발생하는 이유
1. 파이썬 문법 오류
매니페스트는 파이썬 딕셔너리 형태이므로 다음과 같은 문법 실수로 로드가 실패할 수 있습니다:
- 콤마 누락
- 잘못된 들여쓰기
- 닫히지 않은 괄호
- 유효하지 않은 따옴표 사용
이러한 작은 실수 하나가 모듈 로드를 차단합니다.
예시 실수:
'depends': ['base', 'sale'] 'data': ['views/view.xml']
depends 뒤에 콤마가 빠져 있음.
2. 잘못된 의존성 선언
depends 항목에 존재하지 않는 모듈명을 적으면 다음과 같은 문제가 생깁니다:
'depends': ['sales']
실제 의도는
'depends': ['sale']
오타나 잘못된 모듈명을 참조하면 의존성 관련 예외가 발생합니다.
3. data 섹션의 잘못된 파일 경로
data에 존재하지 않는 파일을 명시하면 설치 시 실패합니다:
'data': ['views/missing_view.xml']
파일이 없으면 설치가 중단됩니다.
4. 더 이상 지원되지 않거나 유효하지 않은 키 사용
사용 중인 Odoo 버전에서 지원하지 않는 매니페스트 키는 문제를 일으킬 수 있습니다.
특히 버전별로 허용되는 속성들이 다르므로 Odoo 버전에 맞게 설정해야 합니다.
5. installable이 False로 설정된 경우
예:
'installable': False
이렇게 설정하면 앱 목록에 모듈이 보이지 않습니다.
개발자가 이를 True로 설정하는 것을 깜빡하는 경우가 있습니다.
6. 잘못된 버전 표기
버전 형식이 규칙에 맞지 않으면 특히 배포나 업그레이드 파이프라인에서 문제가 될 수 있습니다.
Odoo 매니페스트 오류를 해결하는 방법
1단계 – 서버 로그 확인
Odoo를 시작하거나 앱 목록을 업데이트할 때 로그를 확인하여 다음을 찾으세요:
SyntaxError
또는 매니페스트 관련 트레이스백
대부분의 경우 오류는 __manifest__.py의 정확한 줄 번호를 가리킵니다.
2단계 – 파이썬 문법 검증
매니페스트 파일을 열어 다음을 점검하세요:
- 딕셔너리 항목 사이의 올바른 콤마
- 정확한 들여쓰기
- 괄호 쌍이 맞는지
- 문자열 따옴표가 유효한지
작은 포맷 실수 하나가 설치를 막을 수 있습니다.
3단계 – 의존성 확인
'depends': []에 나열된 모든 모듈이 실제로 존재하고
정확한 이름으로 표기되었는지
오타가 없는지 검토하세요.
4단계 – 데이터 파일 경로 확인
'data': []에 적힌 파일들이 모듈 디렉토리에 실제로 있는지
모두 존재하는지 확인합니다.
오타나 파일 위치 실수로 인해 경로가 어긋나지 않았는지 점검하세요.
잘못된 파일 경로나 파일 누락이 흔한 원인입니다.
5단계 – 재시작 및 앱 목록 갱신
수정 후에는 다음을 수행하세요:
- Odoo 서버 재시작
- 앱 메뉴 접근
- “앱 목록 업데이트” 클릭
- 그리고 모듈 설치를 다시 시도합니다.
매니페스트 오류를 사전에 막는 방법
- __manifest__.py를 일관된 포맷으로 관리하세요.
- 배포 전에 문법을 검증하세요.
- 의존성은 최소화하고 명확하게 기재하세요.
- 다른 Odoo 버전의 매니페스트를 그대로 복사해 쓰지 마세요 — 버전에 맞게 조정해야 합니다.
- 버전 관리를 통해 변경 이력을 추적하세요.
잘 정리된 매니페스트 파일은 대부분의 설치 문제를 예방합니다.
다솔로(Dasolo)는 어떻게 모듈 설정을 엄격하게 관리하나
매니페스트 오류는 사소해 보일 수 있지만 모듈 설치나 업그레이드를 전면 차단할 수 있습니다. 원인은 대개 문법 오류, 잘못된 의존성 표기, 또는 데이터 파일 참조 실수입니다.
다솔로에서는 매니페스트 관련 실패를 방지하기 위해 다음을 엄격히 관리합니다:
- 문법 검증 절차
- 명확하고 최소한의 의존성 정의
- 정확한 데이터 및 보안 파일 참조
- 버전별 설정 정책 적용
- 스테이징 환경에서 사전 배포 테스트 수행
규율 있는 설정 관리 워크플로우는 배포 중단을 줄이고 환경 간 일관된 모듈 동작을 보장합니다.
결론
Odoo의 “매니페스트 오류”는 모듈 구성 파일에 문법적 문제, 잘못된 의존성, 또는 존재하지 않는 파일 참조가 있을 때 발생합니다. 단순해 보이지만 근본 원인은 종종 체계적인 구성 관리 부족입니다.
매니페스트 구조를 주의 깊게 점검하고 의존성을 검증하며 배포 전 테스트를 거치면 반복적인 설치 실패를 피할 수 있습니다. 깔끔하고 일관된 모듈 구성 프로세스는 안정적이고 확장 가능한 Odoo 운영을 위해 필수적입니다.