multiple definition 에러는 헤더 파일에 일반 함수의 본문(정의)을 작성하고 여러 .cpp 파일에서 그 헤더를 포함했을 때 링크 단계에서 발생하는 대표적인 C++ 링크 에러입니다. 이 글에서는 2026-10-25(KST)에 g++ (Debian 14.2.0-19) 14.2.0으로 재현한 실제 코드와 링커 출력을 바탕으로 ODR(One Definition Rule) 위반 원인과 inline을 비롯한 해결 방법을 정리합니다.
핵심 요약
이 에러는 같은 함수의 정의가 여러 .cpp 파일에 하나씩 들어가 링커가 정의를 두 개 이상 발견할 때 납니다. 헤더에 함수 본문을 쓰면, 그 헤더를 포함한 .cpp마다 정의가 생기기 때문입니다. 헤더 쪽 함수에 inline을 붙이거나, 헤더에는 선언만 두고 정의는 .cpp 한 곳에 두면 해결됩니다.
multiple definition 에러란 무엇입니까?
한 줄 답: multiple definition 에러는 개별 소스 파일을 컴파일할 때가 아니라, 여러 목적 파일(.o)을 하나로 합치는 링크 단계에서 동일한 심볼 정의가 중복될 때 링커(ld/collect2)가 내는 링크 에러입니다.
C++의 ODR(One Definition Rule)에 따르면, 하나의 번역 단위(translation unit) 안에는 변수·함수·클래스 등의 정의가 하나만 있어야 하며, 프로그램 전체에서도 odr-used되는 모든 비-inline 함수나 변수는 오직 하나의 정의만 존재해야 합니다. 헤더에 비-inline 함수 본문을 정의하고 두 개의 .cpp 파일에서 포함하면 프로그램 전체에 정의가 하나만 있어야 한다는 규칙이 깨집니다.
아래는 문제를 재현하는 세 개의 파일입니다.
util.h:
#pragma once
int helper() { return 1; }
a.cpp:
#include "util.h"
int a() { return helper(); }
main.cpp:
#include "util.h"
int a();
int main() { return a() + helper(); }
이 파일들을 g++ -std=c++17 a.cpp main.cpp -o odr_bad 명령으로 빌드하면 종료 상태 1(exit status 1)과 함께 다음 출력이 나옵니다(임시 목적 파일 이름은 ccXXXX로 표기했습니다).
/usr/bin/ld: /tmp/ccXXXX.o: in function `helper()':
main.cpp:(.text+0x0): multiple definition of `helper()'; /tmp/ccXXXX.o:a.cpp:(.text+0x0): first defined here
collect2: error: ld returned 1 exit status
메시지 앞부분이 컴파일러가 아니라 /usr/bin/ld와 collect2로 시작하는 점에서 링크 에러임을 알 수 있습니다. 전처리기나 문법 단계에서 나는 컴파일 에러는 형태가 다르며, 예를 들어 매크로 이름 충돌로 발생하는 컴파일 에러는 expected unqualified-id before numeric constant 에러란? 매크로와 이름이 겹칠 때 C++ 해결 방법 글에서 확인할 수 있습니다.
헤더 가드가 있는데 왜 생깁니까?
한 줄 답: #pragma once나 헤더 가드는 하나의 번역 단위(.cpp 파일 하나) 안에서 같은 헤더가 두 번 포함되는 것만 막아 주므로, 서로 다른 .cpp 파일이 각자 헤더를 포함하는 것까지 막지는 못합니다.
각 .cpp 파일은 서로 독립된 번역 단위로 컴파일됩니다. 따라서 util.h 맨 위에 #pragma once가 있더라도 다음과 같이 처리됩니다.
a.cpp를 컴파일할 때util.h가 한 번 포함되어 목적 파일에helper()의 정의가 들어갑니다.main.cpp를 컴파일할 때도util.h가 한 번 포함되어 목적 파일에helper()의 정의가 또 들어갑니다.- 각 번역 단위 안에서는 정의가 하나뿐이므로 컴파일은 통과하지만, 두 목적 파일을 합치는 링커 입장에서는
helper()정의가 두 개가 되어 충돌합니다.

multiple definition 에러는 어떻게 고칩니까?
한 줄 답: 헤더의 함수 정의에 inline을 붙이거나, 헤더에는 선언만 남기고 정의를 하나의 .cpp 파일로 분리하거나, 파일 내부 전용 복사본이 필요하면 static 또는 익명 이름공간을 사용합니다.
1. 헤더의 함수에 inline 붙이기
헤더에 함수 본문을 그대로 두어야 한다면 함수 선언 앞에 inline 지정자를 붙입니다. 다음은 수정한 util_inline.h입니다.
#pragma once
inline int helper() { return 1; }
a_inline.cpp와 main_inline.cpp는 각각 a.cpp, main.cpp와 내용이 같고 포함하는 헤더만 "util_inline.h"로 바꾼 파일입니다. g++ -std=c++17 a_inline.cpp main_inline.cpp -o odr_inline 명령을 실행하면 에러 없이 링크되며, ./odr_inline; echo $? 실행 결과는 다음과 같습니다.
2
종료 코드 2는 a()가 반환한 1과 helper()가 반환한 1이 더해진 값입니다.
2. 헤더에는 선언만 두고 하나의 .cpp에 정의 분리하기
본문이 없는 함수 선언은 정의가 아니라 선언(declaration)입니다. 헤더에는 선언만 두고 실제 본문(정의)은 단 하나의 .cpp 파일에만 작성하면 프로그램 전체에서 정의가 하나만 존재하게 됩니다(아래 예시는 설명용 코드 조각이며 별도로 실행하지 않았습니다).
// util.h (설명용 예시 — 별도 실행 안 함)
#pragma once
int helper();
// util.cpp (설명용 예시 — 별도 실행 안 함)
#include "util.h"
int helper() { return 1; }
3. static 함수 또는 익명 이름공간 사용하기
헤더의 함수를 static으로 선언하거나 익명 이름공간(anonymous namespace) 안에 두면 내부 연결(internal linkage)을 갖게 됩니다. 이 경우 각 .cpp 파일마다 자기만의 별도 복사본이 생겨 링크 충돌은 나지 않지만, 포함된 파일 수만큼 함수 복사본이 만들어진다는 차이가 있습니다(아래 예시는 설명용 코드 조각이며 별도로 실행하지 않았습니다).
// util.h (설명용 예시 — 별도 실행 안 함)
#pragma once
static int helper() { return 1; }
한편 CMake로 빌드할 때는 같은 .cpp 소스 파일이 타깃에 두 번 추가되지 않았는지, 소스 목록에 한 번만 들어갔는지도 함께 확인해야 하며, 기본적인 CMake 빌드 설정 구성은 aarch64 크로스 컴파일 CMake, toolchain 파일은 어떻게 쓰나 글을 참고할 수 있습니다.
inline은 “인라인 확장”과 같은 뜻입니까?
한 줄 답: 원래 의도는 인라인 치환 힌트였으나, C++98부터 함수의 inline은 “여러 번역 단위에 동일한 정의가 나타나는 것을 허용한다”는 의미가 핵심입니다.
cppreference의 inline 지정자 문서에 따르면, 컴파일러는 inline이 붙지 않은 함수도 인라인 치환할 수 있고 반대로 inline이 붙은 함수를 일반 함수 호출로 처리할 수도 있습니다. 즉 현대 C++에서 inline의 실질적인 역할은 외부 연결(external linkage)을 가진 함수나 변수(C++17부터)가 서로 다른 번역 단위에 여러 번 정의되더라도 모든 정의의 토큰 시퀀스가 동일하다면(예: 같은 헤더를 여러 소스 파일에서 포함) ODR 위반으로 보지 않도록 허용하는 것입니다.
또한 C++17에서는 이 규칙이 변수로 확장되어 inline 변수가 도입되었으며, 이로써 헤더 전용(header-only) 라이브러리를 만들 때 가장 큰 걸림돌이었던 변수 정의 문제가 해결되었습니다. 컴파일러가 실제로 어떤 코드를 만들어 내는지 직접 확인하고 싶다면 C++ Insights란? 컴파일러가 숨겨 둔 코드(람다·range-for)를 직접 보는 법 글에서 소개한 도구를 활용할 수 있습니다.
자주 묻는 질문은 무엇입니까?
한 줄 답: 함수 템플릿, 클래스 정의 내부의 멤버 함수, 헤더의 전역 변수에서도 동일한 ODR 및 inline 규칙이 적용됩니다.
템플릿은 왜 헤더에 정의해도 됩니까?
ODR 규칙상 템플릿 엔티티(함수 템플릿, 클래스 템플릿 등)는 클래스 타입이나 inline 함수·변수와 마찬가지로, 서로 다른 번역 단위에 정의가 나타나고 토큰 시퀀스가 동일하기만 하면 프로그램 안에 여러 정의가 존재하는 것이 허용되기 때문입니다.
클래스 안에서 정의한 멤버 함수는 괜찮습니까?
괜찮습니다. 클래스 정의 내부에서 본문까지 완전히 정의된 함수와 constexpr 함수는 별도로 inline 키워드를 쓰지 않아도 암묵적으로 inline(implicitly inline)으로 취급됩니다.
전역 변수에서도 생깁니까?
생깁니다. 헤더에 비-inline 전역 변수를 정의하면 여러 .cpp에서 포함할 때 똑같이 중복 정의 에러가 발생하므로, 헤더에는 초기값 없는 extern 선언만 두고(초기값 없는 extern은 정의가 아닌 선언입니다) 하나의 .cpp 파일에서 정의하거나, C++17 이상이라면 inline 변수를 사용합니다.
함께 보면 좋은 글은 무엇입니까?
한 줄 답: C++ 컴파일 에러 해결, CMake 빌드 설정, 컴파일러 생성 코드 확인을 다룬 관련 글입니다.
- expected unqualified-id before numeric constant 에러란? 매크로와 이름이 겹칠 때 C++ 해결 방법
- aarch64 크로스 컴파일 CMake, toolchain 파일은 어떻게 쓰나
- C++ Insights란? 컴파일러가 숨겨 둔 코드(람다·range-for)를 직접 보는 법
출처는 어디입니까?
한 줄 답: cppreference의 정의·ODR 문서 및 inline 지정자 문서와 직접 실행한 GCC 결과입니다.
- cppreference — Definitions and ODR (확인 2026-10-25)
- cppreference — inline specifier (확인 2026-10-25)
- 직접 실행 환경:
g++ (Debian 14.2.0-19) 14.2.0(확인 2026-10-25 KST)