Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
start
✓ import { start } from 'directus';
✗ const directus = require('directus'); directus.start();
Used for programmatically starting the Directus server. Requires environment variables to be configured.
stop
✓ import { stop } from 'directus';
✗ const { stop } = require('directus');
Used for programmatically stopping a running Directus server instance gracefully.
DirectusConfig
✓ import type { DirectusConfig } from 'directus';
Type definition for configuring the Directus server when used programmatically. Actual configuration is typically done via environment variables or a config file.
This quickstart demonstrates how to programmatically start a Directus server instance using SQLite, automatically configuring essential environment variables and an admin user for initial setup. It creates a project directory and a database file if they don't exist.
import { start } from 'directus';
import dotenv from 'dotenv';
import path from 'path';
import fs from 'fs';
// Load environment variables from .env file
dotenv.config();
const PROJECT_PATH = path.resolve(__dirname, './directus-project');
const DB_FILE = path.join(PROJECT_PATH, 'database.sqlite');
// Ensure project directory exists
if (!fs.existsSync(PROJECT_PATH)) {
fs.mkdirSync(PROJECT_PATH, { recursive: true });
}
// Set required environment variables for a minimal Directus setup
// Directus will auto-bootstrap a SQLite database and admin user on first run.
process.env.PUBLIC_URL = process.env.PUBLIC_URL ?? 'http://localhost:8055';
process.env.DB_CLIENT = process.env.DB_CLIENT ?? 'sqlite3';
process.env.DB_FILENAME = process.env.DB_FILENAME ?? DB_FILE;
process.env.ADMIN_EMAIL = process.env.ADMIN_EMAIL ?? 'admin@example.com';
process.env.ADMIN_PASSWORD = process.env.ADMIN_PASSWORD ?? 'password';
process.env.SECRET = process.env.SECRET ?? 'a_super_secret_key_that_should_be_long_and_random_for_security';
process.env.PORT = process.env.PORT ?? '8055';
process.env.REFRESH_TOKEN_SECRET = process.env.REFRESH_TOKEN_SECRET ?? 'another_super_secret_key_for_refresh_tokens';
process.env.ACCESS_TOKEN_SECRET = process.env.ACCESS_TOKEN_SECRET ?? 'yet_another_super_secret_key_for_access_tokens';
process.env.KEY = process.env.KEY ?? ''; // Placeholder for process.env.KEY (not always required)
console.log('Attempting to start Directus server...');
start().then(() => {
console.log(`Directus server successfully started on ${process.env.PUBLIC_URL}`);
console.log(`Access the admin panel at ${process.env.PUBLIC_URL}/admin`);
console.log(`Initial Admin User: ${process.env.ADMIN_EMAIL} / ${process.env.ADMIN_PASSWORD}`);
console.log('Note: On first run, Directus will initialize the database schema and create the admin user.');
}).catch((err) => {
console.error('Failed to start Directus server:', err);
process.exit(1);
});
directus --version
Debug
Known issues
breakingDirectus is transitioning its core license from Business Source License (BSL) 1.1 to a custom Monospace Sustainable Core License (MSCL) alongside an updated Innovation Grant, expected to be fully implemented with v12. This new model will introduce software registration keys for both paid and free users (under $5M revenue AND 50 employees) and includes non-compete terms.fixReview the official Directus community posts and documentation regarding the MSCL and Innovation Grant to understand the new terms and potential requirements for license keys and compliance, especially if your organization exceeds the new free tier thresholds.
affects: >=11.x (impacting >=12.0.0)
breakingDirectus v11.17.0 introduced changes related to background data imports and improved build times. Exports previously available from `@directus/` internal packages might have changed due to the adoption of `tsdown`'s `oxc-transform` for improved build performance.fixDevelopers using internal Directus package exports in custom extensions should verify compatibility and update import paths if necessary. Consult the full changelog for details on affected packages.
affects: >=11.17.0
breakingVersion 11.16.0 introduced global draft versioning, which standardizes the display name of any existing version with the key `draft` to 'Draft'. While content and functionality remain unchanged, this can affect custom naming conventions.fixBe aware that custom display names for `draft`-keyed versions will be overwritten. Adjust any documentation or user-facing references to reflect the standardized 'Draft' name. No data migration is required.
affects: >=11.16.0
breakingDirectus 11.0.0 made significant changes to its access control model, moving permissions from roles to policies, which can be attached to roles and directly to users. User permissions are now an aggregate of all attached policies.fixCarefully review and migrate your existing permission structures to the new policy-based model. Ensure all necessary policies are correctly configured and assigned to roles or users to maintain desired access control.
affects: >=11.0.0
breakingStarting with Directus v11.13, the `RELATIONAL_TYPES` constant no longer includes non-relational types (presentation and group types). Custom extensions or external code referencing this constant may break.fixUpdate any custom code or extensions that rely on `RELATIONAL_TYPES` to remove dependencies on the excluded types. Re-evaluate how these types are handled in your custom logic.
affects: >=11.13.0
gotchaDirectus primarily relies on environment variables for configuration. While configuration files (like `.env`, `.json`, `.yaml`, or `.js`) can be used, there might be precedence issues where configuration files could override environment variables in unexpected ways.fixAlways explicitly define critical configurations using environment variables in production environments. Test thoroughly to understand the precedence order if mixing environment variables and configuration files. Refer to Directus documentation for the exact precedence rules.
affects: >=11.0.0
Errors
Common errors & fixes
Error: Database connection failed
Incorrect database connection details in environment variables (e.g., `DB_CLIENT`, `DB_HOST`, `DB_USER`, `DB_PASSWORD`, `DB_DATABASE`) or the database server is not running or accessible.
fixVerify that your database server is running and accessible from the Directus instance. Double-check all `DB_*` environment variables for correct values. For Docker deployments, ensure network connectivity between containers.
Error: Missing environment variable: SECRET
The `SECRET` environment variable, crucial for cryptographic operations, is not set.
fixSet a long, random, and unique string as the `SECRET` environment variable. This is critical for production security. Example: `SECRET='your-long-random-secret-key-here'`.
Address already in use :::8055
Another process is already using the port Directus is trying to bind to (default 8055).
fixChange the `PORT` environment variable to an available port, or stop the process currently using port 8055. For example: `PORT=8080 npx directus start`.
Error: EACCES: permission denied, open '/path/to/directus-project/database.sqlite'
Directus does not have write permissions to the specified directory or file for the SQLite database. This often occurs when using Docker or deploying to restricted file systems.
fixEnsure that the user running the Directus process has read/write permissions to the `DB_FILENAME` (for SQLite) or the directory where it's attempting to create the file. For Docker, map volumes with appropriate user permissions.
Audit
Dependencies
No dependency data recorded yet.