- Published on
linux timeout example: 리눅스 timeout 명령어 사용법
- Authors

- Name
- Indo Yoon


리눅스에서 오래 걸리는 작업이 끝없이 매달리는 상황을 막는 가장 간단한 방법은 timeout 명령어로 실행 시간 상한을 거는 것이에요. timeout의 기본 문법과 자주 쓰는 옵션, 배포 스크립트와 cron에서 어떤 값을 골라야 하는지를 예제 중심으로 정리해요. 서버 운영 중 무한 대기로 배포가 멈추는 사고를 줄이는 데 바로 적용할 수 있어요.

한눈에 보기
timeout은 "정해진 시간 안에 끝나지 않으면 프로세스에 신호를 보내 종료시킨다"는 단일 목적의 명령어예요. 데몬을 따로 띄우거나 래퍼 스크립트를 만들 필요 없이, 실행하려는 명령 앞에 붙이기만 하면 돼요. 그래서 배포 자동화나 정기 작업에서 가장 먼저 추가하는 안전장치로 쓰여요.
- 형식은
timeout [옵션] 시간 명령어 [인자...]예요. - 시간을 지정하지 않으면 명령이 실행되지 않으므로 반드시 값을 적어야 해요.
- 기본으로 보내는 신호는 TERM이고, 시간 초과로 종료되면 종료 코드 124를 돌려줘요.
- TERM을 무시하는 프로그램에는
--kill-after로 KILL을 예약해 두는 편이 안전해요. - 종료 코드를 그대로 활용하려면
--preserve-status를 함께 써요.
timeout 명령어 기본 문법
가장 기본이 되는 형태는 이래요.
timeout [옵션] 시간 명령어 [인자...]
s, m, h, d를 붙이면 각각 다른 단위로 바뀌어요. 접미사를 생략하면 초로 해석돼요. 시간 값은 정수와 접미사의 조합으로 적어요. 스크립트를 읽는 사람을 위해 정수와 접미사를 쓰는 편이 가독성이 좋아요. 소수 형태의 시간도 받아들여요.
timeout 30 curl -sS https://example.com/health
네트워크 요청은 curl 자체의 --max-time 옵션과 timeout을 같이 거는 경우가 많아요. 위 예제는 헬스 체크 요청이 응답 없이 매달릴 때 스크립트 전체가 멈추는 것을 막아요. timeout은 그 바깥에서 전체 실행 시간을 제한하는 역할을 해요. curl 옵션은 연결과 전송 단계를 세밀하게 제어해요.
명령이 정상 종료되면 timeout은 해당 명령의 종료 코드를 그대로 전달해요. 반면 시간 초과로 끊겼을 때는 124를 반환하므로, 스크립트에서 두 경우를 구분해 로그를 남길 수 있어요.
주요 옵션 비교 표
| 옵션 | 역할 | 주로 쓰는 상황 |
|---|---|---|
-s, --signal | 보낼 신호를 지정해요. 기본값은 TERM예요. | 애플리케이션의 정상 종료 처리를 유도하고 싶을 때 |
-k, --kill-after | 신호를 보낸 뒤에도 프로세스가 남아 있으면 KILL을 예약해요. | TERM을 무시하는 프로그램을 확실히 정리할 때 |
--preserve-status | 시간 초과 여부와 무관하게 명령의 실제 종료 코드를 유지해요. | 종료 코드로 성공과 실패를 판정할 때 |
--foreground | timeout이 별도 프로세스 그룹을 만들지 않아요. | TTY 입력이 필요한 대화형 명령을 감쌀 때 |
-v, --verbose | 종료 시 진단 메시지를 출력해요. | 동작을 디버깅하거나 로그로 남길 때 |
대부분의 운영 스크립트는 -k와 --preserve-status 조합만으로도 충분해요. 표에서 알 수 있듯이 옵션은 크게 "어떤 신호를 보낼지", "얼마나 더 기다릴지", "결과를 어떻게 보고할지"로 나뉘어요.
단계별 사용 방법
가장 단순한 형태로 감싸기
실행할 명령 앞에 시간 값을 붙이는 것만으로 끝나요.
timeout 60 ./deploy.sh
이 한 줄이면 배포 스크립트가 정해진 시간을 넘길 때 자동으로 중단돼요. 다만 스크립트 내부에서 자식 프로세스를 띄운 경우, 그 자식까지 항상 정리된다고 가정하면 안 돼요.
종료 신호를 바꾸기
timeout -s INT 30 ./long-task.sh
INT는 터미널에서 Ctrl+C를 눌렀을 때와 같은 신호예요. 애플리케이션이 인터럽트를 받아 정상 종료 훅을 실행하도록 설계되어 있다면, TERM보다 INT가 의도에 맞을 수 있어요.
강제 종료 시점을 추가하기
timeout -k 10 30 ./long-task.sh
먼저 TERM을 보내고, 그 뒤에도 살아 있으면 KILL을 보내요. 신호를 무시하도록 작성된 프로그램이나 서드파티 바이너리를 다룰 때 유용해요.
종료 코드를 그대로 쓰기
timeout --preserve-status 30 ./job.sh
echo $?
--preserve-status가 없으면 시간 초과 시 종료 코드가 124로 바뀌어요. 시간 초과 여부는 별도로 기록하는 편이 좋아요. 작업 자체의 성공과 실패를 스크립트에서 판정해야 한다면 이 옵션을 붙여요.
파이프라인 전체에 걸기
timeout은 하나의 명령에만 적용돼요. 파이프로 연결된 여러 명령을 한꺼번에 제한하려면 셸로 묶어서 실행해요.
timeout 60 bash -c 'producer | consumer'
이렇게 하면 파이프라인 전체가 하나의 실행 단위로 취급되어 시간 제한이 걸려요.
상황별 선택 가이드
ssh나 curl이 응답 없이 매달리면 배포 파이프라인 전체가 대기 상태로 남기 때문이에요. 배포 스크립트에서 원격 서버에 접속하거나 API를 호출할 때는 짧은 시간 제한을 거는 편이 안전해요. 이때는 timeout과 클라이언트 자체 옵션을 같이 사용하는 것이 일반적이에요.
데이터 마이그레이션이나 배치 작업처럼 정상적으로 오래 걸리는 작업에는 여유 있는 값을 잡아야 해요. 너무 짧게 잡으면 작업이 중간에 끊겨 데이터가 어중간한 상태로 남을 수 있으므로, 예상 소요 시간을 먼저 측정한 뒤 그보다 넉넉하게 설정하는 편이 좋아요.
timeout으로 상한을 두면 최소한 실행이 무한정 누적되는 상황은 피할 수 있어요. cron으로 도는 정기 작업은 이전 실행이 끝나지 않았을 때 겹치는 문제가 있어요. 다만 겹침 자체를 막으려면 별도의 잠금 장치가 필요해요.
표기 방식은 systemd.time(7) 문서에 정리되어 있어요. TimeoutStartSec과 TimeoutStopSec 같은 지시자를 통해 시작과 종료 단계의 대기 시간을 정할 수 있어요. systemd로 관리하는 서비스라면 유닛 파일의 시간 제한 설정을 사용해요. 셸 스크립트 안에서 timeout을 쓰는 것과 역할이 겹치므로, 어느 계층에서 제한할지 먼저 정하는 편이 좋아요.
컨테이너를 다룰 때는 오케스트레이션 도구가 제공하는 종료 대기 설정과 timeout이 중복되지 않도록 주의해야 해요. 두 장치가 서로 다른 시점에 신호를 보내면 로그 해석이 어려워져요.
주의할 점
timeout은 명령과 그 자식 프로세스에 신호를 보내지만, 프로그램이 새 세션을 만들거나 프로세스 그룹을 벗어나면 정리가 되지 않을 수 있어요. 백그라운드로 분리되는 데몬 형태의 프로그램을 감쌀 때는 특히 주의해야 해요.
TERM을 무시하도록 작성된 프로그램은 -k 없이는 종료되지 않아요. 운영 환경에서 정리되지 않은 프로세스가 남으면 포트 충돌이나 파일 잠금 문제로 이어질 수 있으므로, 강제 종료 시점을 같이 지정하는 습관이 좋아요.
셸 내장 명령에는 timeout을 직접 적용할 수 없어요. cd나 export 같은 내장 명령을 감싸야 한다면 bash -c로 별도 셸을 띄워 실행해야 해요.
종료 코드 124는 "시간 초과"라는 의미를 가져요. 실제 명령이 실패해서 나온 코드와 구분되지 않으면 장애 원인을 잘못 짚을 수 있으므로, 로그에 시간 초과 여부를 같이 남기는 편이 안전해요.
--foreground는 TTY 입력이 필요한 대화형 프로그램을 감쌀 때 써요. 이 옵션을 쓰면 timeout이 별도 프로세스 그룹을 만들지 않아, 프로그램이 터미널을 직접 제어할 수 있어요.

자주 묻는 질문
시간 초과로 종료됐는지 어떻게 확인하나요?
시간 초과가 발생하면 timeout은 종료 코드 124를 반환해요. 스크립트에서 $? 값을 확인해 124인지 비교하면 시간 초과 여부를 판별할 수 있어요. --preserve-status를 사용한 경우에는 이 구분이 사라지므로, 필요하면 실행 전후로 시각을 기록해 두는 편이 좋아요.
TERM을 무시하는 프로세스는 어떻게 정리하나요?
-k 옵션으로 강제 종료 시점을 예약하면 돼요. 먼저 TERM을 보내고, 지정한 시간이 지나도 프로세스가 남아 있으면 KILL을 보내요. KILL은 프로세스가 정리 작업을 수행할 기회를 주지 않으므로, 임시 파일이나 잠금 해제가 필요한 프로그램이라면 첫 신호는 TERM으로 두는 것이 좋아요.
파이프라인 전체에 시간 제한을 걸 수 있나요?
timeout은 인자로 받은 하나의 명령에만 적용돼요. 여러 명령을 파이프로 연결했다면 bash -c로 묶어 하나의 실행 단위로 만들어야 전체에 제한이 걸려요. 이때 셸 옵션에 따라 파이프의 마지막 명령 종료 코드가 반환된다는 점도 같이 고려해야 해요.
systemd 서비스에도 같은 개념을 적용할 수 있나요?
유닛 파일의 TimeoutStartSec과 TimeoutStopSec 지시자로 시작과 종료 단계의 대기 시간을 지정할 수 있어요. 표기 방식은 systemd.time(7) 문서를 따르며, 셸 스크립트에서 timeout을 쓰는 대신 서비스 계층에서 관리할 수 있어요. 두 방식을 동시에 쓰면 어느 쪽이 먼저 동작했는지 로그에서 헷갈릴 수 있어요.
출처
- GNU coreutils 매뉴얼, timeout invocation: https://www.gnu.org/software/coreutils/manual/html_node/timeout-invocation.html
- man7.org, timeout(1) 매뉴얼 페이지: https://man7.org/linux/man-pages/man1/timeout.1.html
- man7.org, systemd.time(7) 매뉴얼 페이지: https://man7.org/linux/man-pages/man7/systemd.time.7.html
신호 종류와 프로세스 그룹 동작을 이해하면 timeout을 어디에 걸어야 하는지 판단하기가 한결 쉬워져요. 배포 스크립트에서 프로세스가 남아 포트가 잠기는 문제를 다룬다면 리눅스 프로세스와 시그널 정리 글을 같이 읽어 보시면 좋아요.