Invidious Development Dependencies: Complete Guide to Crystal, PostgreSQL, and System Libraries

Invidious development requires three categories of dependencies: Crystal library shards (defined in shard.yml), system-level libraries and compilers (managed via install-dependencies.sh), and development-only tools for testing and linting.

Invidious is an open-source YouTube front-end written in Crystal and maintained by the iv-org/invidious repository. Building the application from source requires installing the Crystal toolchain alongside native system libraries that the compiler links against at build time, plus the database servers and shard packages defined in the project configuration.

Crystal Library Dependencies (shard.yml)

Runtime dependencies for Invidious are declared in [shard.yml](https://github.com/iv-org/invidious/blob/master/shard.yml) and fetched by the Crystal package manager. These libraries compile directly into the final binary:

• pg – PostgreSQL driver providing database connectivity
• sqlite3 – SQLite3 driver for optional NewPipe data import/export functionality
• kemal – The HTTP/web framework handling routing and request processing
• protodec – Protocol buffer utilities for YouTube API communication
• athena-negotiation – Content-negotiation helpers for HTTP responses
• http_proxy – Proxy support for outgoing requests

To install these dependencies after cloning the repository:

shards install

This command downloads the specified versions and compiles them into the local lib/ directory, making them available to the Invidious source code.

System-Level Runtime Dependencies

The [scripts/install-dependencies.sh](https://github.com/iv-org/invidious/blob/master/scripts/install-dependencies.sh) script automates installation of system packages across major Linux distributions (apt/Debian/Ubuntu, dnf/CentOS/Fedora, pacman/Arch, and zypper/openSUSE). The script installs:

• Crystal compiler (version ≥ 1.10 and < 2.0)
• PostgreSQL server (primary datastore)
• Git (for repository cloning and updates)
• librsvg2-bin (provides rsvg-convert for CAPTCHA image generation)

Additionally, the script installs development headers that Crystal's standard library requires for compilation:

• OpenSSL (libssl-dev) – HTTPS/TLS support
• libxml2 (libxml2-dev) – XML parsing
• libyaml (libyaml-dev) – YAML configuration file parsing
• libgmp (libgmp-dev) – Big number arithmetic
• libevent (libevent-dev) – Event loop and scheduler
• PCRE (libpcre3-dev) – Regular expression engine
• SQLite3 (libsqlite3-dev) – Database driver support
• zlib (zlib1g-dev) – Compression
• readline (libreadline-dev) – Command-line editing

Without these -dev packages, the Crystal compiler cannot link against native C APIs when building the extensions required for SSL, XML processing, and YAML handling.

Development-Only Dependencies

The development_dependencies section in shard.yml specifies tools used exclusively during development and testing:

• spectator – A testing framework for writing and executing Crystal specs
• ameba – A static-analysis linter for code quality

These are fetched only when running test suites or linting commands. They do not compile into production binaries and are not required for deployment.

How Dependencies Integrate at Runtime

In src/invidious.cr (lines 63‑70), the application initializes a database connection using the pg shard with credentials from config.yml. The kemal framework then binds to the configured port and handles HTTP routing using the compiled-in dependencies.

System libraries expose native C APIs that Crystal's standard library consumes. For example, OpenSSL headers enable the OpenSSL::SSL::Context module for HTTPS client connections to YouTube's servers, while libxml2 supports XML response parsing.

Installing Dependencies on Ubuntu/Debian

The fastest method uses the provided installation script:

git clone https://github.com/iv-org/invidious.git
cd invidious
bash scripts/install-dependencies.sh

The script performs the following actions:

1. Detects your distribution package manager automatically
2. Adds the official Crystal repository to your APT sources
3. Installs crystal, postgresql, git, librsvg2-bin, and all required development headers

After installation completes, verify PostgreSQL is running:

sudo systemctl start postgresql

Verifying Development Dependencies

To confirm all Crystal dependencies are correctly installed and the test suite passes:

crystal spec

This command executes the spectator framework and runs the full test suite against your local PostgreSQL instance. To check code style with the linter:

ameba

Summary

• Three categories comprise Invidious dependencies: Crystal shards (shard.yml), system libraries (install-dependencies.sh), and development tools.
• Key files to inspect are shard.yml for library versions and scripts/install-dependencies.sh for system package lists.
• Crystal version constraint is strictly >= 1.10 and < 2.0, enforced by the compiler and CI pipelines.
• PostgreSQL is the mandatory primary datastore, while SQLite3 support remains optional for specific import/export features.

Frequently Asked Questions

What Crystal version is required to build Invidious?

Invidious requires Crystal compiler versions greater than or equal to 1.10 but strictly less than 2.0. The install-dependencies.sh script automatically selects a compatible version from the official Crystal repositories when run on supported Linux distributions.

Can I use SQLite instead of PostgreSQL for development?

No, PostgreSQL is mandatory for running Invidious. The sqlite3 shard exists only for importing and exporting NewPipe subscription data. The application initializes its primary database connection via the pg shard in src/invidious.cr, and all core functionality depends on PostgreSQL-specific features.

What is the fastest way to install all dependencies on a fresh server?

Run the scripts/install-dependencies.sh script as root or with sudo privileges. This bash script automatically detects your Linux distribution (Debian, Ubuntu, Fedora, CentOS, Arch, or openSUSE), adds the correct Crystal repository, and installs all system libraries, compilers, and PostgreSQL in a single command.

Are development dependencies required for production deployments?

No. The spectator testing framework and ameba linter defined under development_dependencies in shard.yml are only necessary for running tests and code analysis. Production builds use shards install --production (or simply exclude development dependencies) to compile smaller binaries without these tools.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}