Skip to main content

​
Installation

Evidence can be installed in multiple ways depending on your workflow and environment. Choose the method that works best for you. The VSCode extension provides the easiest way to get started with Evidence, including guided setup and integrated development tools.
1

Install the extension

Install the Evidence extension from the VSCode Marketplace:

Evidence VSCode Extension

Click to install from the Visual Studio Marketplace
Or search for “Evidence” in the VSCode Extensions panel (Ctrl/Cmd+Shift+X).
2

Create a new project

Open the Command Palette (F1 or Ctrl/Cmd+Shift+P) and run:
Evidence: New Evidence Project
Follow the prompts to create your project in your desired location.
3

Start Evidence

Click the Start Evidence button in the bottom status bar.Start Evidence button in VSCodeThis will:
  • Install all required dependencies
  • Start the Evidence development server
  • Open your browser automatically to http://localhost:3000
On Windows, the first startup can take a couple of minutes as dependencies are installed.

​
Command line installation

Install Evidence directly from your terminal using your preferred package manager. 
npx degit evidence-dev/template my-evidence-app
cd my-evidence-app
npm install
npm run sources
npm run dev
Your Evidence app will be available at http://localhost:3000.
The degit command clones the Evidence template without git history, giving you a clean starting point.

​
Install with dbt

You can install Evidence inside your existing dbt project to create an analytics monorepo. 
cd path/to/your/dbt/project
npx degit evidence-dev/template reports
npm --prefix ./reports install
npm --prefix ./reports run sources
npm --prefix ./reports run dev
This creates an Evidence project in a reports folder within your dbt project, allowing you to:
  • Version control your models and reports together
  • Make coordinated changes across your data transformation and reporting layers
  • Keep related code in a single repository
This setup currently requires terminal access and cannot be done from the dbt Cloud UI.

​
GitHub Codespaces

Run Evidence in a cloud-based development environment without any local installation.

Launch Evidence Codespace

Create a new Evidence Codespace (opens GitHub)
Codespaces runs much faster on the VSCode Desktop app. After the Codespace boots, select the hamburger menu → Open in VS Code Desktop.

​
Docker installation

Run Evidence in a Docker container for consistent, isolated environments.
Detailed Docker setup instructions are available in the Evidence documentation. The basic approach involves creating a Dockerfile that installs Node.js and Evidence dependencies.

​
Evidence Studio (cloud IDE)

Evidence Studio is an AI-powered cloud IDE that provides the fastest way to build with Evidence.

Try Evidence Studio

Get started with Evidence Studio - no installation required
Features:
  • No local setup required
  • AI-powered code assistance
  • Instant previews
  • Integrated deployment

​
System requirements

​
Minimum requirements

  • Node.js 18 or higher (check with node --version)
  • npm, yarn, or pnpm for package management
  • 2GB RAM for development
  • Modern web browser (Chrome, Firefox, Safari, Edge)
  • Node.js 20+
  • 4GB+ RAM (especially for large datasets)
  • SSD storage for faster builds
Evidence automatically increases Node memory limit to 4GB when running build commands. You can override this by setting NODE_OPTIONS=--max-old-space-size=8192 for 8GB.

​
Connect your database

After installation, you’ll want to connect your own data source. Evidence supports multiple databases and data warehouses.

​
Supported data sources

PostgreSQL

PostgreSQL and compatible databases

Snowflake

Snowflake data warehouse

BigQuery

Google BigQuery

DuckDB

Local DuckDB databases

MySQL

MySQL and MariaDB

Databricks

Databricks SQL

CSV/Parquet

Flat files (CSV, Parquet)

MotherDuck

DuckDB in the cloud

SQLite

SQLite databases

​
Add a data source

1

Navigate to settings

While your dev server is running, visit http://localhost:3000/settings.
2

Add new source

Click Add new source and select your database type from the list.
3

Configure connection

Enter your connection details. These are saved in:
  • sources/[source_name]/connection.yaml - non-secret configuration
  • sources/[source_name]/connection.options.yaml - encrypted credentials (base64 encoded)
4

Create source queries

Add .sql files to your source directory to define queries:
sources/my_database/orders.sql
select * from orders
where order_date >= '2024-01-01'
These queries run in your database’s native SQL dialect.
5

Run sources

Execute your source queries to populate the data cache:
npm run sources

​
CSV files

To use CSV files as a data source:
  1. Navigate to http://localhost:3000/settings
  2. Select Add new source → CSV
  3. Upload your CSV file or place it in sources/[source_name]/
  4. Run npm run sources to build the data cache
Your CSV data will be available to query like any other data source.

​
CLI commands

Evidence provides several CLI commands for development and deployment:

​
Development

npx evidence dev

​
Advanced options

Build only changed sources
npx evidence sources --changed
Build specific sources
npx evidence sources --sources my_database,other_db
Build specific queries
npx evidence sources --queries orders,customers
Strict mode (fail on error)
npx evidence sources --strict
Debug mode
npx evidence dev --debug

​
Environment debugging

View all Evidence environment variables: 
npx evidence env-debug
Include values (⚠️ shows secrets): 
npx evidence env-debug --include-values

​
Project structure

After installation, your Evidence project will have this structure: 
my-evidence-app/
├── pages/               # Your markdown pages
│   └── index.md        # Homepage
├── sources/            # Data source configurations
│   └── needful_things/ # Demo database
│       ├── connection.yaml
│       └── orders.sql  # Source query
├── static/             # Static assets (images, CSS)
├── components/         # Custom Svelte components (optional)
├── .evidence/          # Build artifacts (auto-generated)
├── package.json        # Dependencies and scripts
└── evidence.config.yaml # Evidence configuration

​
Updating Evidence

To update Evidence to the latest version: 
npx evidence upgrade
This command updates all Evidence packages to their latest compatible versions.
Check the Evidence changelog before upgrading to see what’s new.

​
Next steps

Follow the quickstart

Build your first Evidence app in 5 minutes

Learn the syntax

Understand Evidence-flavored Markdown

Explore components

Browse the full component library

Deploy your app

Deploy to Netlify, Vercel, or your own infrastructure

​
Troubleshooting

Evidence requires Node.js 18 or higher. Check your version with node --version and upgrade if needed using nvm or by downloading from nodejs.org.
On Windows, you may need to install the Windows Build Tools:
npm install --global windows-build-tools
If port 3000 is already in use, specify a different port:
npx vite dev --port 3001
Verify your connection credentials in sources/[name]/connection.yaml and ensure your database is accessible from your development machine.
If you encounter issues during installation, reach out on Slack or open an issue on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us