Quarto 1.10.18 맥 PDF 내보내기 실패: 2026 점검

먼저 증상을 세 갈래로 나누세요. PDF 파일이 생성되지 않았는지, 명령이 오류로 종료됐는지, 파일은 있지만 내용이 빠졌는지 기록합니다. 이 구분을 건너뛰면 문서 처리 오류와 컴파일 오류를 같은 문제로 다루게 됩니다.

• [ ] 실행한 명령 전체와 터미널 출력을 별도 파일에 저장합니다.
• [ ] 실패한 문서의 복사본을 보관합니다. 원본에서 바로 설정을 바꾸지 마세요.
• [ ] quarto --version과 quarto check 결과를 기록합니다. 진단 항목은 Quarto 문제 해결 문서에서 확인할 수 있습니다.
• [ ] 프로젝트 디렉터리, 입력 파일, 출력 형식, 실패 지점을 메모합니다.
• [ ] 연구 데이터 없이 제목과 짧은 본문만 둔 최소 문서로 PDF 렌더링을 시도합니다.

최소 문서도 실패하면 프로젝트 내용보다 설치된 PDF 도구 체인이나 경로를 먼저 살펴봅니다. 최소 문서가 통과하면 원래 프로젝트의 설정과 구성 요소를 한 종류씩 되돌려 원인을 찾으세요. 실패 기록을 지우거나 패키지를 한꺼번에 갱신하면 비교에 필요한 단서가 사라질 수 있습니다.

명령이 문서를 읽기 전부터 실패한다면 현재 작업 디렉터리와 실제 호출되는 Quarto 실행 파일부터 점검하세요. 다른 설치 경로의 실행 파일이 먼저 선택되거나, 프로젝트 폴더가 아닌 곳에서 렌더링해 설정 파일을 놓칠 수 있습니다.

프로젝트 안에서 입력 파일과 출력 형식이 맞는지도 확인합니다. quarto render는 지정한 입력 문서와 형식에 따라 렌더링을 수행합니다. 실행 방법은 Quarto render 명령 참고와 프로젝트 설정 문서를 기준으로 확인하세요.

YAML 들여쓰기, 형식 이름, 필터 경로, 템플릿 참조는 서로 다른 원인입니다. 오류가 난 설정을 한 번에 여러 개 고치지 말고, 한 항목을 바꿀 때마다 명령과 로그를 저장하세요. 설정을 고친 뒤에는 최소 문서 또는 해당 문서만 다시 렌더링해 변화가 있었는지 확인합니다. 설정 하나를 바꿨는데 오류 지점이 그대로라면 그 변경은 원인 해결로 보지 말고 다음 항목을 점검하세요.

R 또는 Python 코드 블록에서 멈췄다면, PDF 엔진을 바꾸기 전에 오류가 발생한 단계부터 확인합니다. 코드 블록 실행이 실패한 것인지, 코드 실행은 끝났지만 결과 PDF 컴파일에서 멈춘 것인지 로그의 오류 위치와 출력 파일로 구분하세요.

R과 Python 실행 환경이 원인인지 확인합니다

문서가 지정한 실행 엔진, R 환경이나 Python 인터프리터, 필요한 패키지와 커널이 현재 터미널에서 사용 가능한지 확인합니다. 편집기에서 실행되더라도 Quarto를 호출한 셸에서 같은 환경을 찾는다는 보장은 없습니다.

실제 연구 데이터를 복사하지 말고, 오류가 난 부분을 대표하는 작은 코드 블록으로 재현하세요. 캐시나 동결된 출력이 켜져 있다면 현재 코드의 새 결과가 아니라 이전 결과를 보고 있는지도 확인합니다. 코드 실행이 성공한 로그와 PDF 컴파일 로그를 따로 남기면 두 단계의 경계가 명확해집니다.

원본 프로젝트에서 캐시를 한꺼번에 지우거나 환경 전체를 업데이트하지 마세요. 먼저 프로젝트 복사본에서 한 가지 변경만 시험하고, 결과가 달라졌을 때만 그 조치를 원본에 반영합니다.

Quarto PDF 렌더링에서 LaTeX 오류가 보이면, 메시지에 나온 누락 항목과 실제로 호출된 PDF 엔진을 먼저 확인하세요. Quarto PDF 엔진 안내는 PDF 엔진 선택과 TinyTeX 사용 방법을 설명합니다. Quarto가 맥의 기본 경로에 있는 도구를 자동으로 쓴다고 단정하지 말고 진단 결과에서 실행 경로를 확인해야 합니다.

lualatex를 찾지 못할 때 실제 경로를 확인합니다

lualatex를 찾을 수 없다는 오류라면 Quarto가 호출한 엔진 이름과 경로, 터미널의 PATH, 설치된 TeX 배포판을 대조합니다. pdf-engine 설정이 프로젝트 설정이나 문서 설정에 지정돼 있는지도 살펴보세요. PDF 형식 설정 참고에서 엔진 관련 설정 이름과 적용 위치를 확인할 수 있습니다.

다음에는 현재 TeX 환경으로 렌더링한 로그를 보관한 뒤, 필요할 때만 Quarto가 관리하는 TinyTeX 환경을 별도로 점검합니다. 두 도구 체인을 동시에 설치하거나 경로를 함께 바꾸면 어느 쪽이 오류를 해결했는지 알기 어렵습니다. 새 환경에서도 같은 최소 문서가 실패하면 프로젝트 설정을 계속 바꾸기보다 엔진 설치와 경로를 다시 확인하세요.

한글 글꼴이나 특수 기호가 빠지면 문서에서 지정한 PDF 엔진, 글꼴 이름, 실제 설치 여부와 해당 글꼴의 문자 지원 범위를 확인합니다. 특정 엔진으로 바꿨다고 모든 글꼴 문제가 해결되는 것은 아닙니다. 제출 대상 컴퓨터에서 같은 글꼴을 사용할 수 있는지도 별도로 확인해야 합니다.

그림이 빠지거나 위치가 어긋나면 파일이 실제로 존재하는지, 상대 경로가 프로젝트 기준으로 맞는지, 생성 단계에서 그림 파일이 만들어지는지 확인하세요. 참고 문헌이 갱신되지 않거나 교차 참조가 어긋나면 LaTeX 문제라고 단정하지 마세요. 인용 처리와 참고 문헌 파일 경로를 살피고, Quarto 인용 및 참고 문헌 안내에 따라 문서 설정과 오류 로그를 대조합니다.

PDF를 열어 페이지 누락, 글꼴 대체, 그림 잘림, 인용 목록과 표기 결과를 직접 확인하세요. 화면에 파일이 생성됐다는 사실만으로 제출 형식이나 분석 결과가 검증된 것은 아닙니다.

• 최소 문서도 실패하면 → 프로젝트를 더 수정하지 말고 Quarto 진단 결과, 실행 경로, PDF 엔진 설치 상태를 확인합니다.
• 최소 문서는 통과하고 원본 문서만 실패하면 → 프로젝트 복사본에서 설정, 코드, 그림, 인용 자료를 한 종류씩 되돌립니다.
• 코드 실행 단계에서 실패하면 → R 또는 Python 환경과 패키지를 확인하고, 코드 실행 성공 여부를 PDF 컴파일 결과와 분리합니다.
• PDF는 생성되지만 글꼴·인용·그림이 잘못되면 → 누락된 구성 요소의 경로와 설정을 확인한 다음 실제 출력물을 검수합니다.
• 내 맥에서는 재현되지 않고 다른 환경에서만 실패하면 → 운영체제와 도구 경로 차이를 기록하고, 민감 정보를 제거한 복사본으로 격리 검증을 고려합니다.

최소 문서가 통과하면 프로젝트 복사본에서 원래 요소를 단계적으로 복원합니다. 템플릿, 코드, 참고 문헌, 그림 파일을 한 번에 되돌리지 마세요. 각 단계마다 렌더링 명령과 오류 로그를 보관하면 어떤 구성 요소가 실패를 다시 일으켰는지 찾기 쉽습니다.

최종 확인은 다음 항목을 모두 마친 뒤 완료로 기록합니다.

• [ ] 재현에 사용한 Quarto 버전과 렌더링 명령을 기록했습니다.
• [ ] PDF 엔진과 호출 경로를 확인했습니다.
• [ ] 코드 블록이 현재 환경에서 실행됐고, 오래된 캐시 결과를 새 결과로 오인하지 않았습니다.
• [ ] 한글 글꼴, 그림, 참고 문헌과 교차 참조가 PDF에 올바르게 반영됐습니다.
• [ ] 페이지 구성과 제출 형식을 사람이 직접 확인했습니다.
• [ ] 재현에 사용한 설정과 의존성을 팀원이 다시 확인할 수 있게 남겼습니다.

프로젝트마다 TeX 설치 경로, 글꼴, R·Python 의존성이 다르면 개인 맥에서만 통과하는 절차를 팀의 재현 가능한 작업 흐름으로 간주하기 어렵습니다. 기존 로컬 환경은 이미 설치된 도구와 설정이 얽혀 원인 분리가 까다로울 수 있고, 여러 사람이 같은 조건을 맞추기도 쉽지 않습니다. 반대로 원격 macOS 환경은 로컬과 다른 점이 있으므로, 먼저 민감 정보를 제거한 프로젝트로 렌더링 절차가 재현되는지 검증해야 합니다. 장기간의 고정 작업이나 물리 장비 연결이 필요하다면 직접 관리하는 맥이 더 적합할 수 있습니다.

본인 맥에서 반복 실패하고 연구 절차가 macOS를 요구한다면, CALMVPS 이용 요금과 사용 조건을 살펴본 뒤 비식별 프로젝트로 필요한 흐름을 검증하세요. 조건이 맞으면 CALMVPS 맥 환경 이용 안내에서 이용 방법을 확인할 수 있습니다. 원격 환경의 렌더링 성공은 코드와 연구 결과의 정확성, 논문 제출 규정에 대한 최종 확인을 대신하지 않습니다.