direnv 사용법 정리
direnv 사용법 정리
프로젝트 디렉토리에 들어가면 환경변수를 자동으로 로드하고, 나가면 해제해주는 도구가 direnv 입니다. 언어/프레임워크와 상관없이 “프로젝트 단위 환경”을 관리할 때 유용합니다.
1. 언제 쓰나 (환경변수 활용)
아래 항목 중 하나라도 해당되면 환경변수를 꾸준히 쓰게 됩니다.
- 로컬/스테이징/프로덕션 설정 분리
- API 키, 토큰, DB 접속 정보 같은 민감 값 관리
- 프로젝트별 포트, 로그 레벨, 피처 플래그
- 프로젝트마다 다른 런타임/툴체인 옵션
direnv는 이런 설정을 디렉토리 기준으로 자동 적용해주기 때문에, 전역 환경변수를 건드리지 않고도 안전하게 관리할 수 있습니다.
2. direnv vs dotenv
둘 다 환경변수 관리와 관련이 있지만, 동작 레벨이 다릅니다.
요약 비교
| 구분 | direnv | dotenv |
|---|---|---|
| 동작 위치 | Shell 레벨 | 애플리케이션 레벨 |
| 자동 적용 | O (디렉토리 진입 시) | X (코드에서 로드 필요) |
| 보안 승인 | 필요 (direnv allow) | 보통 필요 없음 |
| 추천 상황 | 개발환경 관리 | 앱 설정 관리 |
실무에서 자주 쓰는 조합
- 로컬 개발 환경:
direnv - 애플리케이션 설정:
dotenv - 함께 쓰는 경우가 많음:
.env에 값 저장,.envrc에서dotenv .env로드
언어별 dotenv 라이브러리 예시
- Node.js:
dotenv - Python:
python-dotenv - Java:
dotenv-java - Ruby:
dotenv - Go:
godotenv - PHP:
vlucas/phpdotenv
3. Spring Boot 관점
Spring Boot는 application.yml 중심의 설정 체계가 있어서 dotenv는 필수가 아닙니다. 반대로 direnv는 셸/디렉토리 단위 환경 관리라서 프로젝트 전환이나 툴체인 변경을 자동화하는 쪽에 강점이 있습니다.
- Spring 설정(앱 레벨):
application.yml+ 환경변수 override - 개발 환경(셸 레벨):
direnv로 디렉토리 진입/이탈 시 자동 적용
즉, Spring 환경에서는 dotenv는 선택 사항이고, direnv는 개발 워크플로를 정리하는 도구로 볼 수 있습니다.
4. 설치
macOS (Homebrew)
1
brew install direnv
Ubuntu / Debian
1
2
sudo apt-get update
sudo apt-get install direnv
Fedora
1
sudo dnf install direnv
Arch
1
sudo pacman -S direnv
5. 쉘에 hook 추가
direnv는 쉘이 디렉토리를 이동할 때 동작합니다. 사용하는 쉘의 설정 파일에 hook을 추가합니다.
zsh
1
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
bash
1
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
fish
1
echo 'direnv hook fish | source' >> ~/.config/fish/config.fish
설정 후 쉘을 재시작하거나 source ~/.zshrc 등을 실행합니다.
6. 기본 흐름
1) .envrc 생성
프로젝트 루트에 .envrc 파일을 만들고 환경변수를 정의합니다.
1
2
3
export APP_ENV=local
export API_URL=http://localhost:8080
export PATH="$PWD/bin:$PATH"
2) 허용(allow)
보안상, .envrc는 명시적으로 허용해야 적용됩니다.
1
direnv allow
이후 해당 디렉토리에 들어갈 때 자동으로 환경변수가 로드됩니다.
3) 변경 시 재허용
.envrc를 수정하면 다시 허용해야 합니다.
1
direnv allow
7. 자주 쓰는 패턴
런타임/툴체인 설정
1
2
export JAVA_HOME="/usr/lib/jvm/temurin-17"
export PATH="$JAVA_HOME/bin:$PATH"
로컬 전용 설정 분리
.envrc에 민감한 값을 직접 넣기보다, 로컬 파일로 분리해 불러옵니다.
.envrc:
1
2
dotenv .env
dotenv_if_exists .env.local
.gitignore:
.env
.env.local
.envrc.local
별도 파일을 직접 소스하려면 아래처럼 사용할 수 있습니다.
1
source_env_if_exists .envrc.local
.envrc vs .envrc.local 구분 기준
공유해도 되는 설정과 개인/민감 설정을 분리할 때 사용합니다.
.envrc: 팀 공통 설정 (PATH, 런타임 버전, 기본 옵션).envrc.local: 개인 전용 설정 (토큰, 비밀번호, 개인 포트, 로컬 경로)
예시:
1
2
3
4
5
6
7
# .envrc (공유)
layout node
export JAVA_HOME="/usr/lib/jvm/temurin-17"
# .envrc.local (개인)
export AWS_PROFILE=my-dev
export DB_PASSWORD=local-secret
direnv stdlib: layout 활용
direnv는 자주 쓰는 프로젝트 구성에 맞춘 layout 기능을 제공합니다. 필요한 PATH/환경변수를 자동으로 구성해줍니다.
Node
1
layout node
$PWD/node_modules/.bin 이 PATH에 추가됩니다.
Python
1
layout python python3
.direnv 아래에 venv를 만들고 로드합니다.
Go
1
layout go
GOPATH와 PATH가 프로젝트 기준으로 설정됩니다.
PHP
1
layout php
$PWD/vendor/bin 이 PATH에 추가됩니다.
8. 보안/주의사항
direnv allow는 해당 디렉토리의.envrc를 신뢰한다는 뜻입니다.- 저장소를 클론한 직후에는 내용을 확인하고 허용합니다.
.envrc에 토큰/패스워드를 직접 넣기보다 별도 파일로 분리하는 것이 안전합니다.
9. Windows에서는?
Windows 네이티브 환경에서는 일반적으로 사용하지 않습니다. 대신 WSL 환경에서 Linux 셸과 함께 사용하는 경우가 많습니다.
10. 트러블슈팅
변경한 .envrc가 반영되지 않을 때
1
direnv allow
적용 상태 확인
1
direnv status
11. 참고
- https://direnv.net/
- https://github.com/direnv/direnv