Official openai 패키지는 Python 3.8+ 에서 동작해. 설치는 pip install openai 한 줄. 근데 꼭 venv 안에서 해 — global python 에 박으면 system Python 과 충돌하고 청소가 지옥.
Pin 은 lockfile 에서
SDK 는 빠르게 ship 돼. Major version 에서 가끔 parameter shape 깨져 (max_tokens → max_completion_tokens 가 최근 사례). Unpinned dependency 는 금요일 오후 deploy 가 월요일에 조용히 깨지는 길 — 주말 사이 pip 가 새 minor version resolve 했기 때문.
실전 패턴
requirements.txt 에 lower bound 박고 (openai>=1.78,<2), lockfile (uv.lock, poetry.lock, pip-compile 출력) 에 resolved version freeze. Lower bound 는 의도적으로 schedule 에 따라 bump — 사고로 bump 되는 게 아니라.
설치 검증
python -c "from openai import OpenAI; print(OpenAI().models.list().data[0].id)" — API key 환경 변수 셋업되어 있으면 첫 모델 ID 가 print 돼. 안 되면 Auth 트랙 다시 보고.