Docker compose up no configuration file provided 오류 해결

VSCode 터미널 실행 위치와 compose.yaml 파일 경로를 함께 확인하는 흐름입니다.


docker compose up 실행 중 no configuration file provided: not found 오류가 보이면 대부분 Docker Compose가 현재 폴더에서 설정 파일을 찾지 못한 상태입니다. 먼저 터미널 위치가 프로젝트 루트인지 확인하고, 그 폴더에 compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml 중 하나가 있는지 확인하면 됩니다.


포트 충돌이나 Docker Desktop 설치 문제보다 먼저 봐야 할 것은 “어디에서 명령어를 실행했는가”입니다. VSCode 터미널, Windows PowerShell, WSL, Mac zsh 모두 현재 위치가 다르면 같은 프로젝트라도 Compose 파일을 찾지 못할 수 있습니다.


오류 메시지 원문

아래 메시지는 docker compose up 명령을 실행했지만 현재 폴더 또는 상위 폴더에서 Compose 설정 파일을 찾지 못했을 때 볼 수 있습니다.


no configuration file provided: not found

환경이나 Docker Compose 버전에 따라 아래처럼 표시될 수도 있습니다.


can't find a suitable configuration file in this directory or any parent

먼저 볼 결론
이 오류는 컨테이너 내부 오류가 아니라 실행 위치와 Compose 파일 경로 문제일 가능성이 큽니다. compose.yaml 파일이 있는 폴더에서 docker compose up을 실행하거나, -f 옵션으로 파일 경로를 직접 지정합니다.


이 오류가 발생하는 대표 상황

Docker Compose는 현재 작업 폴더를 기준으로 Compose 파일을 찾습니다. GitHub에서 받은 프로젝트를 VSCode로 열거나, 터미널을 하위 폴더에서 열었을 때 아래 상황이 자주 생깁니다.


  • Compose 파일이 없는 폴더에서 docker compose up을 실행한 경우
  • VSCode 터미널이 프로젝트 루트가 아닌 src, app, backend 같은 하위 폴더에서 열린 경우
  • 파일명이 compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml 중 하나가 아닌 경우
  • Compose 파일이 docker, infra, deploy 폴더 안에 있는데 -f 옵션을 쓰지 않은 경우
  • GitHub 프로젝트 전체가 아니라 일부 하위 폴더만 VSCode에서 열어 실행한 경우

현재 위치 확인하기

가장 먼저 터미널이 어느 폴더를 보고 있는지 확인합니다. Mac zsh, Linux, WSL에서는 pwd를 사용합니다.


pwd

예를 들어 아래처럼 나오면 현재 위치는 프로젝트 루트가 아니라 backend 하위 폴더일 수 있습니다.


/Users/name/project/backend

Windows PowerShell에서는 아래 명령어로 현재 위치를 확인합니다.


Get-Location

출력된 경로가 compose.yaml 파일이 있는 폴더와 같은지 확인합니다. 다르면 먼저 프로젝트 루트로 이동해야 합니다.


Compose 파일이 있는지 확인하기

현재 폴더에 어떤 파일이 있는지 확인합니다. Mac zsh, Linux, WSL에서는 아래 명령어를 사용합니다.


ls

Windows PowerShell에서는 아래 명령어를 사용합니다.


dir

Compose 파일 이름만 빠르게 확인하려면 아래처럼 찾을 수 있습니다.


ls compose.yaml compose.yml docker-compose.yml docker-compose.yaml

파일이 있으면 파일명이 출력됩니다. 파일이 없다는 메시지가 나오면 현재 폴더가 잘못되었거나 Compose 파일이 다른 폴더에 있는 상태입니다.


확인 결과 가능한 원인 다음 조치
파일명이 보임 현재 폴더가 맞을 가능성이 큼 docker compose up 실행
파일이 없다고 나옴 프로젝트 루트가 아닐 수 있음 상위 폴더 또는 README 실행 위치 확인
다른 폴더에 파일이 있음 Compose 파일 경로가 분리됨 -f 옵션으로 파일 직접 지정

프로젝트 루트로 이동해서 다시 실행하기

Compose 파일이 프로젝트 루트에 있다면 해당 폴더로 이동한 뒤 다시 실행합니다. 프로젝트 루트는 보통 README.md, package.json, pyproject.toml, compose.yaml 같은 파일이 함께 있는 최상위 폴더입니다.


cd 프로젝트폴더명

폴더 이동 후 파일 목록을 다시 확인합니다.


ls

Compose 파일이 보이면 기본 실행 명령을 다시 입력합니다.


docker compose up

Windows PowerShell에서도 흐름은 같습니다. 현재 위치를 확인하고, Compose 파일이 있는 폴더로 이동한 뒤 실행합니다.


Get-Location
dir
docker compose up

-f 옵션으로 Compose 파일 직접 지정하기

Compose 파일이 현재 폴더가 아니라 다른 폴더에 있으면 -f 옵션으로 파일 위치를 직접 지정할 수 있습니다. 현재 폴더에 compose.yaml이 있다면 아래처럼 실행합니다.


docker compose -f compose.yaml up

Compose 파일이 docker 폴더 안에 있다면 경로를 포함해 지정합니다.


docker compose -f ./docker/docker-compose.yml up

-f 옵션은 파일을 찾지 못하는 상황에서 가장 직접적인 해결 방법입니다. 다만 매번 긴 경로를 입력해야 한다면 VSCode에서 프로젝트 루트 폴더를 다시 열거나 README에 적힌 실행 위치를 기준으로 터미널을 여는 편이 더 편합니다.


VSCode 터미널에서 자주 생기는 실수

VSCode에서 이 오류가 자주 나는 이유는 터미널 위치와 사용자가 보고 있는 파일 위치가 다를 수 있기 때문입니다. 왼쪽 파일 탐색기에는 compose.yaml이 보이는데, 터미널은 하위 폴더에서 열려 있을 수 있습니다.


하위 폴더만 열어 둔 경우

GitHub 프로젝트 전체가 아니라 backend 또는 frontend 폴더만 VSCode로 열면 상위 폴더의 Compose 파일을 찾지 못할 수 있습니다. 이 경우 프로젝트 최상위 폴더를 다시 열고 터미널을 새로 열어 확인합니다.


터미널이 이전 경로를 유지하는 경우

VSCode 창을 바꿔도 기존 터미널 세션이 이전 경로를 유지할 수 있습니다. 새 터미널을 열고 pwd 또는 Get-Location으로 현재 위치를 다시 확인합니다.


README 실행 위치와 다른 곳에서 실행한 경우

일부 프로젝트는 README에 cd docker, cd infra, cd deploy처럼 실행 위치를 따로 안내합니다. 이때는 루트 폴더에서 바로 docker compose up을 실행하면 파일을 찾지 못할 수 있습니다.


Windows·WSL·Mac에서 확인할 차이

명령어의 목적은 같지만 운영체제와 셸에 따라 경로 표시와 파일 확인 명령이 조금 다릅니다. 특히 Windows에서 PowerShell과 WSL을 함께 쓰는 경우, 같은 프로젝트라도 경로가 다르게 보일 수 있습니다.


환경 현재 위치 확인 파일 확인
Mac zsh pwd ls
Linux·WSL pwd ls
Windows PowerShell Get-Location dir

WSL에서 실행한다면 Windows 경로가 아니라 WSL 안의 Linux 경로에서 프로젝트를 보고 있는지 확인합니다. 예를 들어 WSL에서는 /home/name/project처럼 보이고, PowerShell에서는 C:\Users\name\project처럼 보일 수 있습니다.


Windows와 WSL을 함께 쓸 때
PowerShell에서 보이는 폴더와 WSL 터미널에서 보이는 폴더가 다를 수 있습니다. Docker Desktop WSL Integration 문제가 함께 보이면 Compose 파일 경로 문제와 Docker 연결 문제를 나누어 확인하는 것이 좋습니다.


파일명은 어떤 것을 써야 하나요?

Docker Compose에서 기본으로 찾는 파일명은 compose.yaml 또는 compose.yml입니다. 기존 프로젝트 호환을 위해 docker-compose.yml, docker-compose.yaml도 많이 사용됩니다.


초보자라면 새 프로젝트에서는 compose.yaml을 우선 사용하고, GitHub에서 받은 프로젝트라면 이미 있는 파일명을 그대로 사용하는 편이 안전합니다. 파일명을 마음대로 compose.dev.yaml, local-compose.yml처럼 바꿨다면 기본 명령으로는 찾지 못할 수 있으므로 -f 옵션을 사용합니다.


docker compose -f compose.dev.yaml up

port is already allocated 오류와 다른 점

no configuration file provided는 Docker Compose가 설정 파일을 찾지 못했다는 뜻입니다. 반면 port is already allocated는 Compose 파일을 읽고 컨테이너 실행을 시도했지만, 이미 사용 중인 포트와 충돌했다는 뜻입니다.


오류 핵심 원인 먼저 볼 것
no configuration file provided Compose 파일을 찾지 못함 현재 폴더, 파일명, -f 경로
port is already allocated 호스트 포트가 이미 사용 중 사용 중인 포트, Compose 포트 매핑

재발 방지 체크리스트

같은 오류가 반복된다면 프로젝트를 열 때와 터미널을 열 때의 기준을 정해 두는 것이 좋습니다.


  • README의 실행 위치를 먼저 확인합니다.
  • compose.yaml 파일이 있는 폴더를 프로젝트 루트로 엽니다.
  • VSCode 터미널을 새로 열어 현재 위치를 다시 확인합니다.
  • 파일명이 Docker Compose가 인식하는 형식인지 확인합니다.
  • Compose 파일이 하위 폴더에 있으면 -f 옵션으로 경로를 지정합니다.
  • PowerShell과 WSL 중 어느 환경에서 실행하는지 구분합니다.

공식 자료로 더 확인하기

Compose 파일명, docker compose up 동작, -f 옵션은 Docker 공식 문서에서 기준을 확인할 수 있습니다. 프로젝트 구조가 복잡하거나 여러 Compose 파일을 조합하는 경우 공식 문서를 함께 보는 것이 좋습니다.


Docker Compose 공식 문서

Docker Compose의 기본 개념과 Compose로 여러 컨테이너 애플리케이션을 정의하고 실행하는 흐름을 확인할 수 있습니다.

Docker Compose 공식 문서 확인하기

Compose 파일 참조 문서

compose.yaml에서 서비스, 네트워크, 볼륨 등을 어떻게 정의하는지 공식 기준으로 확인할 수 있습니다.

Docker Compose file reference 확인하기

docker compose up 명령어 문서

docker compose up이 서비스를 생성하고 시작하는 방식, 주요 옵션과 실행 흐름을 확인할 수 있습니다.

docker compose up 공식 문서 확인하기

docker compose 명령어 옵션 문서

-f 옵션으로 Compose 파일 이름과 경로를 직접 지정하는 방법을 확인할 수 있습니다.

Docker Compose 명령어 옵션 확인하기

함께 보면 좋은 글

Docker Desktop 기본 오류 점검
Compose 파일 경로는 맞는데 Docker Desktop 자체가 느리거나 실행이 불안정하다면 권한, 리소스, 디스크 용량을 함께 확인할 수 있습니다.
Docker Desktop 설치 2026: 권한·리소스·느려짐·디스크 용량 폭증 해결 체크리스트

VSCode와 Docker 연결 문제
VSCode Dev Container에서 Docker daemon 연결 오류가 함께 보인다면 터미널 경로 문제와 Docker 실행 상태를 나누어 확인해야 합니다.
Dev Container Docker daemon 연결 오류 해결: VSCode에서 Is Docker running? 뜰 때

VSCode Dev Container 실행 점검
프로젝트 폴더를 열었는데 Dev Container 명령이 보이지 않거나 컨테이너로 다시 열 수 없다면 VSCode 폴더 열기 기준도 함께 확인할 수 있습니다.
VSCode Dev Container 오류 해결: Reopen in Container가 안 뜰 때 체크할 것

WSL Docker 연결 문제
Windows WSL에서 Docker 명령이 연결되지 않는다면 Docker Desktop Integration 설정을 따로 확인해야 합니다.
WSL에서 Docker가 연결되지 않을 때: Docker Desktop Integration 설정법

자주 묻는 질문

Q1. compose.yaml과 docker-compose.yml 중 무엇을 써야 하나요?

새 프로젝트라면 compose.yaml을 우선 사용하면 됩니다. 기존 프로젝트에서는 이미 있는 docker-compose.yml을 그대로 사용해도 됩니다. 중요한 것은 Docker Compose가 인식하는 파일명이거나, 다른 파일명일 때 -f 옵션으로 직접 지정하는 것입니다.


Q2. VSCode에서만 no configuration file provided 오류가 나는 이유는 무엇인가요?

VSCode 터미널이 프로젝트 루트가 아닌 하위 폴더에서 열렸을 가능성이 큽니다. 파일 탐색기에는 compose.yaml이 보여도 터미널 위치가 다르면 Compose가 파일을 찾지 못할 수 있습니다. 새 터미널을 열고 pwd 또는 Get-Location으로 현재 위치를 확인합니다.


Q3. Compose 파일이 다른 폴더에 있으면 어떻게 실행하나요?

-f 옵션으로 파일 경로를 직접 지정합니다. 예를 들어 docker compose -f ./docker/docker-compose.yml up처럼 실행할 수 있습니다. 경로가 길고 자주 실행한다면 README에 적힌 실행 위치를 확인하고 해당 폴더에서 터미널을 여는 편이 편합니다.


Q4. docker compose와 docker-compose 명령어는 다른가요?

docker compose는 Docker CLI에 통합된 Compose V2 방식이고, docker-compose는 예전 방식의 별도 명령어로 볼 수 있습니다. 최근 Docker Desktop 환경에서는 보통 docker compose를 사용합니다. 기존 프로젝트 문서가 오래되었다면 명령어 표기가 다를 수 있습니다.


이 오류는 컨테이너 문제가 아니라 현재 터미널 위치와 Compose 파일 경로를 먼저 확인해야 하는 문제입니다.