원문 iv-org/invidious · 공식 문서 저장소 메타(2026-10-28
gh api재확인): AGPL-3.0, 주 언어 Crystal, 2018-02-07 생성, Stars 약 25,800, 최신 릴리스v2.20261022.0(2026-10-22). 10-11 캡처 시점은 Stars 약 25,200,v2.20260804.1.
한 줄 요약
YouTube 영상을 YouTube 사이트 대신 Invidious 서버를 거쳐 보는 웹 앱이다. 광고와 추적이 없고, 브라우저에서 자바스크립트를 꺼도 돌아가며, 구독도 Google 계정과 따로 관리한다. 남이 운영하는 공개 인스턴스를 고르면 바로 쓸 수 있고, 직접 호스팅할 수도 있다.
사용자 기능
- 가벼운 화면, 광고·추적 없음, 자바스크립트 불필요, 밝은·어두운 테마, 홈 화면 구성 변경
- Google과 무관한 구독 목록, 구독 채널 전체 알림
- 오디오 전용 모드(모바일에서 백그라운드 재생), YouTube 댓글 지원(README 기능 목록에 10월 중 추가된 항목), Reddit 댓글 표시
- 데이터 이동: YouTube·NewPipe·FreeTube에서 구독을, YouTube·NewPipe에서 시청 기록을 가져온다. 구독은 NewPipe·FreeTube로 내보낼 수 있다.
- 개발자용: 임베드 지원, 공개 Developer API. 공식 YouTube API를 쓰지 않는다. 기여자 라이선스 동의(CLA)도 요구하지 않는다.
README는 브라우저 확장 Privacy Redirect를 강하게 추천한다. YouTube 주소를 Invidious 인스턴스로 바꿔 주고, 다른 사이트에 박힌 YouTube 영상도 Invidious로 갈아 끼운다.
직접 호스팅: companion이 필수가 됐다
공식 설치 문서 맨 위에 “마이그레이션 필요”가 붙어 있다. invidious-companion 이 예전 보조 도구 inv-sig-helper와 youtube-trusted-session-generator를 모두 대체했다. companion은 youtube.js 기반 TypeScript 서비스로, 영상 스트림 처리와 PO 토큰 생성(YouTube가 정식 클라이언트인지 확인하려고 요구하는 토큰)을 맡는다. 소스에서 빌드한 개발용 구성은 “companion 없이는 재생이 안 된다”고 문서가 못 박는다.
- 하드웨어: Invidious와 companion을 합쳐 디스크 20GB 이상, 여유 RAM 2GB 이상(정기 재시작 전제). 공개 인스턴스라면 디스크 60GB·RAM 4GB·2 vCPU·200Mbps·월 20TB 트래픽 정도를 권한다. 소스 컴파일엔 여유 RAM 2.5GB가 든다.
- Docker Compose(운영용): 이미지는 Docker Hub가 아니라 Quay에만 있다. Quay 자체가 자유 소프트웨어라는 이유다. Invidious·companion·PostgreSQL 14 세 컨테이너를 띄우고, 비밀 키를 두 개 만든다. Invidious용
hmac_key와 둘이 내부 통신에 쓰는invidious_companion_key인데, 같은 값을 쓰지 말라고 한다. - 저장소를 클론해야 한다. DB 초기화 스크립트와 SQL 디렉터리를 PostgreSQL 컨테이너에 마운트하기 때문이다.
YouTube 차단과 싸우는 운영
공식 문서의 “YouTube 오류 해설”은 사실상 차단 대응 안내서다. 공개 인스턴스 이용자는 읽을 필요 없고, 다른 인스턴스로 옮기면 된다고 먼저 밝힌다.
| 증상 | 원인 | 문서가 권하는 대응 |
|---|---|---|
| 429 응답(최대 24시간) | 구독 갱신 트래픽 과다, 구독 채널이 너무 많음, API 남용 | channel_refresh_interval을 기본값으로 두기, pubsub 설정 후 갱신 간격을 240분으로 늘리기, IP 변경 |
| ”봇이 아닌지 확인하려면 로그인하세요” | 비공식 클라이언트 탐지, 데이터센터·VPN IP 차단 | 최신 버전 + companion 사용, companion 쪽 프록시로 IP 변경, IPv6 주소 순환 |
| PO 토큰 초기화가 너무 오래 걸림 | IP 차단, 또는 YouTube 플레이어 ID가 바뀌어 companion이 새 암호화를 못 풂 | 서버 IP로 youtube.com 재생을 직접 확인(ssh -D SOCKS 프록시), companion 로그 확인, 차단이 아니면 이슈 확인 |
| 재생 URL이 403 | 음악·저작권 영상의 IP 고정 스트림, 대량 다운로드로 IP 차단 | Invidious 쪽 프록시로 IP 변경, IPv6 순환, URL을 만든 IP에서 재생 |
어느 방법도 복구를 보장하지 않는다고 문서가 거듭 적는다. 팀은 이메일 지원을 하지 않고 Matrix·IRC에서만 묻게 한다.
메모
- X에서는 “YouTube Premium을 끊고 Invidious로 갈아탔다”는 스페인어 글(@naldzyul, 2026-10-10)이 퍼졌다. 구독을 한 번에 옮길 수 있고, 2024년 이후 Google이 공개 인스턴스를 계속 막고 있으니 집 서버에 직접 두는 편이 낫다는 주장이다. 위 차단 대응 표가 그 이유를 보여 준다.
- README는 이용 책임을 지지 않으며, 불법 다운로드 같은 부적절한 사용에 대한 책임도 거부한다고 명시한다.
- 화면 번역은 Weblate로 관리하며 계정 없이도 제안할 수 있다.
- 영상을 내려받아 정리하는 쪽 도구는 2026-04-05-open-source-video-download-extensions, 위키의 멀티미디어 지도는 moc-multimedia 참고.
- companion의 설정 항목·HTTP API·플레이어 변경 대응은 2026-10-11-github-iv-org-invidious-companion에 따로 정리했다.
- 최신 릴리스
v2.20261022.0(2026-10-22): 새 기능 없이 정비 위주다. 영상 ID 정규식 검증, 이미지 오류 응답의 가짜Content-Length제거,ytimg.com요청에User-Agent추가. 직접 호스팅한다면 소스 빌드에 Crystal 1.22.0이 필요하고(미지원 버전이면 컴파일 오류), OCI 이미지는 OpenSSL 3.6.5를 쓴다. AI로 사람에게 글을 쓰거나 답하는 것을 금지하는 정책도 추가됐다. 10-28 재확인 시 공식 문서의 설치·YouTube 오류 페이지는 10-11 캡처와 같았다. - Invidious·companion 공식 이미지를 백엔드로 그대로 쓰고 YouTube와 같은 화면·WARP 경유·라이브 자막을 얹은 파생 클라이언트: 2026-11-01-github-biolend83-tubehaus.
- 웹 프런트엔드가 아니라 로그인한 개인 계정으로 쓰는 네이티브 데스크톱 쪽 대안(YouTube Music 전용, Rust·egui): 2026-11-16-github-grapedjuice-ytm-rs.