Skip to main content

ndev

ndev

Universal, Zero-Config Local PHP & Web Development Stack for Windows and Linux.

PyPI Version Python Versions License

ndev Interactive Terminal UI Dashboard


ndev is an all-in-one developer environment manager that isolates, orchestrates, and runs multi-version PHP runtimes, Nginx web server, MariaDB / MySQL, Redis in-memory store, phpMyAdmin, Mailpit email sandbox, local SSL certificates (mkcert), and public HTTP tunnels (ngrok) on Windows 10/11 and Linux (Debian, Ubuntu, openSUSE Tumbleweed, and openSUSE Leap).


Key Features

  • Multi-Version PHP Environment:
    • Windows: Zero-compilation prebuilt official binaries from windows.php.net (PHP 5.6 – 8.5, Thread-Safe & Non-Thread-Safe, x64/x86).
    • Linux: Sandboxed, unprivileged source compilation with bubblewrap and self-healing multiarch library paths (Debian/Ubuntu multiarch and openSUSE /usr/lib64).
  • Process Orchestration & FastCGI / FPM:
    • Windows: Multi-process php-cgi.exe FastCGI worker pools load-balanced through Nginx upstream blocks.
    • Linux: Native php-fpm worker daemons over isolated Unix sockets (~/.ndev/run/php<ver>.sock).
  • Interactive Asynchronous TUI Dashboard (ndev ui):
    • Full-screen real-time terminal UI built with Textual for live monitoring, batch start/stop/restart, on-the-fly CLI PHP version switching, folder-picker virtual host creator, and live log tailing.
  • Automated Nginx Virtual Hosts (ndev vhost):
    • Generates Nginx server blocks with custom FastCGI upstreams, HTTP $\rightarrow$ HTTPS redirects, trusted local SSL certificates, and hosts file mappings.
  • In-Memory Store (ndev redis):
    • Native background Redis server management (6379) with interactive redis-cli terminal integration.
  • Local Email Sandbox (ndev mailpit):
    • Embedded zero-dependency SMTP email catcher (127.0.0.1:1025) and web inbox (http://127.0.0.1:8025).
  • Database & Web Administration (ndev db & ndev pma):
    • Portable MariaDB server (3306) with user/database management CLI tools and local phpMyAdmin (http://127.0.0.1:8080).
  • Single-Command Stack Upgrader (ndev upgrade):
    • Automated version scanning and non-destructive upgrading for Nginx, MariaDB, Redis, Mailpit, phpMyAdmin, mkcert, and Composer.

Architecture & Platform Mapping

ndev/
├── main.py                 # Cross-platform dispatcher & runtime detector
├── common/                 # Shared utilities, configs, logger, GitHub API
├── win/                    # Windows native subsystem (FastCGI, Shims, Click CLI, TUI)
│   ├── core/               # php, services, fcgi, vhost, db, redis_core, mailpit, pma, upgrade
│   └── templates/          # Nginx virtual host configuration templates
└── linux/                  # Linux native subsystem (PHP-FPM, Typer CLI, TUI, Chroot)
    ├── php/                # Source resolver, downloader, extensions, builder
    ├── chroot/             # Bubblewrap sandbox manager
    └── runtime/            # FPM, PMA, Mailpit, and systemd daemons
Subsystem Windows 10/11 (ndev-win) Linux (Debian, Ubuntu, openSUSE Tumbleweed/Leap) (ndev-linux)
PHP Distribution Precompiled binaries from windows.php.net Compiles from official source via bubblewrap sandbox
Process Model Multi-worker php-cgi.exe pools via Nginx upstream Native php-fpm daemons over Unix domain sockets
CLI & PATH Global batch shims in %USERPROFILE%\.ndev\shims\ Symlinks in ~/.local/bin/
Privilege Elevation Win32 ShellExecuteExW (runas) only for hosts sudo for Nginx and /etc/hosts
Web Server Portable Nginx in %USERPROFILE%\.ndev\nginx\ System Nginx via apt install nginx or zypper install nginx
Database Portable MariaDB in %USERPROFILE%\.ndev\mariadb\ System MariaDB via apt install mariadb-server or zypper install mariadb mariadb-client
In-Memory Cache Portable Redis in %USERPROFILE%\.ndev\redis\ System Redis via apt install redis-server or zypper install redis
Email Sandbox Standalone prebuilt Mailpit binary Standalone prebuilt Mailpit binary
phpMyAdmin Served via PHP CLI server (http://127.0.0.1:8080) Served via PHP CLI server (http://127.0.0.1:8080)
Local SSL Standalone mkcert.exe in shims\ System mkcert via apt/zypper or auto GitHub download
TUI Dashboard Asynchronous Textual TUI (ndev ui) Asynchronous Textual TUI (ndev ui)

Directory Structure & Layout

Windows Layout (%USERPROFILE%\.ndev)

%USERPROFILE%\.ndev\
├── certs\                  # Local SSL certificates and cacert.pem CA bundle
├── downloads\              # Cached zip downloads
├── mariadb\                # Portable MariaDB installation & data directory
│   ├── bin\                # mysqld.exe, mysql.exe, mysqldump.exe
│   └── data\               # Database storage
├── nginx\                  # Portable Nginx installation
│   ├── conf\
│   │   ├── nginx.conf      # Main Nginx config (includes ndev-vhosts/*.conf)
│   │   └── ndev-vhosts\    # Virtual host configurations (*.conf)
│   ├── logs\               # Nginx access/error logs per virtual host
│   └── temp\               # FastCGI and proxy client temporary body storage
├── php\
│   └── <version>\          # Extracted PHP binaries (php.exe, php-cgi.exe, php.ini, ext/)
├── pma\                    # Standalone phpMyAdmin installation & config.inc.php
├── redis\                  # Portable Redis server and redis-cli binaries
├── run\                    # Active PID and FastCGI worker state files (JSON)
├── shims\                  # Global batch shims for PATH (php, composer, mysql, redis-cli, mailpit, ndev, etc.)
├── mailpit.db              # Persistent message database for Mailpit
└── config.json             # Global configuration (ports, worker counts)

Linux Layout (~/.ndev)

~/.ndev/
├── bin/                    # Standalone binaries (mailpit)
├── builds/                 # Source tarballs and compilation build directories
├── cache/                  # Download and build cache
├── certs/                  # Local SSL certificates and mkcert root CA
├── chroot/                 # Sandboxed development packages and build root
├── downloads/              # Downloaded source archives
├── logs/                   # Service and daemon logs (pma.log, mailpit.log, etc.)
├── php/
│   └── <version>/          # Compiled PHP installations (bin/, sbin/, etc/php.ini, etc/php-fpm.d/)
├── phpmyadmin/             # Standalone phpMyAdmin installation & config.inc.php
├── run/                    # Active PID and Unix domain socket files (*.sock, *.pid)
├── current                 # Symlink pointing to the currently active PHP version directory
├── mailpit.db              # Persistent message database for Mailpit
└── config.toml             # Global build and runtime configuration

Installation

Standard Installation via PyPI

Install ndev-stack using pip or pipx:

# Using pip
pip install ndev-stack

# Or using pipx (isolated application environment)
pipx install ndev-stack

Note: The package is published on PyPI as ndev-stack, which provides the global commands ndev, ndev-win, and ndev-linux.

Development / Source Installation

git clone https://github.com/ankitkaran99/ndev.git
cd ndev
pip install -e .

Quick Start Guide

Windows 10 / 11

# 1. Install ndev-stack
pip install ndev-stack

# 2. Download and configure portable stack (Nginx, MariaDB, Redis, mkcert, Mailpit, Composer)
ndev setup

# 3. Add shims to user PATH (one-time setup for global CLI access)
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.ndev\shims", "User")
$env:Path += ";$env:USERPROFILE\.ndev\shims"

# 4. Verify installation & launch interactive dashboard
ndev doctor
ndev ui

Linux (Debian / Ubuntu)

# 1. Install system build dependencies
sudo apt update
sudo apt install -y bubblewrap build-essential pkg-config nginx mkcert redis-server default-mysql-client
mkcert -install

# 2. Install ndev-stack
pip install ndev-stack

# 3. Bootstrap runtime environment and shims
ndev setup
export PATH="$HOME/.local/bin:$PATH"

# 4. Verify installation & launch interactive dashboard
ndev doctor
ndev ui

Linux (openSUSE Tumbleweed / Leap)

# 1. Install system build dependencies & tools
sudo zypper refresh
sudo zypper install -y bubblewrap gcc gcc-c++ make pkg-config nginx mariadb mariadb-client curl redis \
    sqlite3-devel oniguruma-devel libxcrypt-devel libcurl-devel libxml2-devel libopenssl-devel \
    libzip-devel libicu-devel libsodium-devel libpng16-devel libjpeg8-devel libwebp-devel \
    freetype2-devel libbz2-devel gmp-devel readline-devel zlib-devel

# Optional: install mkcert for local SSL (available natively in Tumbleweed or auto-installed by ndev)
sudo zypper install -y mkcert 2>/dev/null || true
mkcert -install 2>/dev/null || true

# 2. Install ndev-stack
pip install ndev-stack

# 3. Bootstrap runtime environment and shims
ndev setup
export PATH="$HOME/.local/bin:$PATH"

# 4. Verify installation & launch interactive dashboard
ndev doctor
ndev ui

Quick Command Reference

Command Action
ndev ui Launch real-time Textual TUI dashboard (aliases: tui, dashboard)
ndev available List available PHP releases (--archives for legacy versions)
ndev install <ver> Install / compile a PHP version (8.4, 8.3, 7.4, etc.)
ndev use <ver> Switch active CLI PHP version on PATH
ndev current Show active CLI PHP version
ndev list List installed PHP versions and daemon / worker pool status
ndev start <target> Start service or pool (all, nginx, mariadb, redis, pma, mailpit, <ver>)
ndev stop <target> Stop service or pool (all, nginx, mariadb, redis, pma, mailpit, <ver>)
ndev restart <target> Restart service or pool (all, nginx, mariadb, redis, pma, mailpit, <ver>)
ndev reload nginx Reload Nginx configuration without downtime
ndev status View real-time service status dashboard
ndev ctl Interactive terminal service control menu
ndev vhost Interactive virtual host creation wizard with local SSL
ndev vhost-list List all configured virtual hosts
ndev vhost-remove Remove virtual host and clean up hosts file
ndev db Interactive SQL database management wizard
ndev redis Manage Redis server or launch interactive redis-cli
ndev mailpit Manage local email sandbox (install, start, stop, launch, open)
ndev pma Manage phpMyAdmin background service (http://127.0.0.1:8080)
ndev ext Manage PECL extensions (list, install, enable, disable)
ndev grok Public HTTP tunneling for local virtual hosts via ngrok
ndev postgres Manage PostgreSQL server (install, start, stop, restart, status)
ndev mongodb Manage MongoDB server (install, start, stop, restart, status)
ndev module list List all dynamic modules and status in <userdir>/.ndev/modules/
ndev module <action> Manage dynamic module lifecycle (install, start, stop, restart, status, open)
ndev module create Scaffold a new dynamic module with manifest and template code
ndev upgrade Check for and upgrade stack components (Nginx, MariaDB, Redis, PMA, Mailpit, mkcert, Composer)
ndev upgrade --check Check component versions against upstream releases without upgrading
ndev shell Interactive developer subshell pre-loaded with PHP/Composer/MySQL/Redis on PATH
ndev shim Manage Windows binary shims and PATH registration (list, init, add, rm)
ndev doctor Run environment diagnostics and health checks
ndev logs View and tail service and virtual host logs
ndev clean Clean up downloads cache and stale runtime state

Detailed Usage Guide

1. Interactive Terminal UI Dashboard (ndev ui)

Launch the modern, responsive Textual TUI dashboard for real-time monitoring and process control:

ndev ui
# Aliases: ndev tui, ndev dashboard
  • Live Status Grid: Monitor real-time status, PIDs, and active ports for Nginx, MariaDB, Redis, PMA, Mailpit, and PHP worker pools.
  • One-Click Component Setup & Upgrades: Install uninstalled services (Redis, PMA, Mailpit, Nginx, MariaDB, mkcert, Composer) or upgrade existing components with single-click UI actions.
  • Interactive Virtual Host Manager: Create new virtual hosts (+ Create VHost) with automatic local SSL (mkcert) and an integrated folder-picker dialog.
  • PHP Runtime Management: Install any PHP version (+ Install PHP), uninstall versions (✖ Uninstall Selected), or change the active CLI PHP version via dropdown.
  • Batch Actions: One-click Start All, Stop All, Restart All, and Reload Nginx from the persistent sidebar.
  • Integrated Log Tail Viewer: Select and inspect live logs for Nginx, MariaDB, Redis, PHP, and Virtual Hosts.

2. PHP Version Management

# List available PHP releases (from php.net / windows.php.net)
ndev available
ndev available --archives    # include legacy releases (5.6 - 7.3)

# Install a PHP version (prebuilt on Windows, source-compiled on Linux)
ndev install 8.4

# List locally installed PHP versions and daemon/pool status
ndev list

# Switch globally active CLI PHP version
ndev use 8.4

# Show current active CLI PHP version
ndev current

# Uninstall a PHP version
ndev uninstall 7.4

3. Service & Process Management

# Start / Stop / Restart a PHP pool or individual service
ndev start 8.4
ndev stop 8.4
ndev restart 8.4

# Control core services
ndev start nginx
ndev start mariadb
ndev start redis
ndev start pma
ndev start mailpit

# Batch operations
ndev start all
ndev stop all
ndev restart all

# Reload Nginx configuration without downtime
ndev reload nginx

# View service status
ndev status

4. Virtual Host Management (vhost)

Create and manage local Nginx sites mapped to 127.0.0.1:

# Interactive wizard (auto-prompts for domain, document root, PHP version, and SSL)
ndev vhost

# Create a standard HTTP virtual host
ndev vhost --domain project.local --root /path/to/project --php 8.4

# Create an HTTPS virtual host with trusted local SSL certificates (mkcert)
ndev vhost --domain project.local --root /path/to/project --php 8.4 --ssl

# List all configured virtual hosts
ndev vhost-list

# Remove a virtual host (removes Nginx conf and cleans hosts file)
ndev vhost-remove --domain project.local

5. Redis In-Memory Store (redis)

Manage the local Redis server and launch the interactive redis-cli:

# Start Redis server
ndev redis start
ndev start redis

# Check Redis status
ndev redis status
ndev status redis

# Open interactive redis-cli terminal
ndev redis cli

# Stop or restart Redis server
ndev redis stop
ndev redis restart

Laravel / Symfony / WordPress Configuration:

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

6. SQL Database Manager (db) & phpMyAdmin (pma)

Manage MySQL/MariaDB databases, users, and web administration:

# Launch interactive database management wizard
ndev db

# Create database and user
ndev db create-db mydb --owner myuser
ndev db create-user myuser --new-password secret --grant-db mydb

# Export & import database dumps
ndev db export-db mydb -o backup.sql
ndev db import-db mydb backup.sql

# Start phpMyAdmin web UI
ndev start pma
ndev pma

7. Local Email Sandbox (mailpit)

Catch every outgoing e-mail your local applications send using Mailpit:

# Start Mailpit (auto-installs if not present)
ndev mailpit start
ndev start mailpit

# Open Web UI in default browser
ndev mailpit launch
ndev mailpit open

# Stop or restart Mailpit
ndev mailpit stop
ndev mailpit restart

Configuring Mailpit in your Project:

Laravel (.env):

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

PHP (php.ini):

[mail function]
SMTP = 127.0.0.1
smtp_port = 1025

8. Stack Upgrade Engine (upgrade)

Scan for and upgrade stack components (Nginx, MariaDB, Redis, PMA, Mailpit, mkcert, Composer) safely against latest upstream releases:

# Check for available updates across all stack components
ndev upgrade --check

# Upgrade all components to latest stable releases
ndev upgrade

# Upgrade a specific component
ndev upgrade redis
ndev upgrade mailpit
ndev upgrade pma

9. Diagnostics & Developer Tools

# Run full environment health check
ndev doctor

# Launch pre-configured developer subshell
ndev shell

# Tail live logs for services or virtual hosts
ndev logs
ndev logs 8.4
ndev logs nginx

# Tunnel local virtual host to public web via ngrok
ndev grok

# Clean download cache and temporary files
ndev clean

10. Extensible Dynamic Modules (ndev module)

ndev features a modular architecture where core services (nginx, mariadb, php, phpmyadmin, ngrok) are augmented with dynamic modules (mailpit, redis, postgres, mongodb, and custom community modules) located in <userdir>/.ndev/modules/<module_name>/.

Module Commands:

# List all discovered modules and running status
ndev module list

# Manage module lifecycle
ndev module install mailpit
ndev module start redis
ndev module status postgres
ndev module status mongodb
ndev module open mailpit     # Opens web UI if available
ndev module restart redis
ndev module stop redis

# Direct convenience commands also work seamlessly:
ndev start mailpit
ndev stop redis
ndev postgres start
ndev postgres status
ndev mongodb start
ndev mongodb status

# Scaffold a new custom module
ndev module create my-service --display-name "My Custom Service" --category queue --port 9000

Module Structure (~/.ndev/modules/<name>/):

~/.ndev/modules/my-service/
├── manifest.json   # Module metadata, ports, categories, and web UI definitions
└── module.py       # Python lifecycle handler (is_installed, install, start, stop, restart, status, open_ui)

Sample manifest.json:

{
  "name": "my-service",
  "display_name": "My Custom Service",
  "version": "1.0.0",
  "description": "Custom queue worker service",
  "category": "queue",
  "ports": [9000],
  "web_ui": "http://127.0.0.1:9000",
  "platforms": ["windows", "linux"],
  "entrypoint": "module.py"
}

Dynamic modules appear automatically inside the TUI Dashboard (ndev ui), where you can start, stop, restart, and open web interfaces with a single click.

📖 Looking to build your own module? See the full ndev Module Developer Guide (MODULE_DEV_GUIDE.md) for step-by-step instructions, manifest schema, and boilerplate templates.


Configuration Files

Windows

  • Global Settings: %USERPROFILE%\.ndev\config.json
  • PHP Configuration: %USERPROFILE%\.ndev\php\<version>\php.ini
  • Nginx Main Config: %USERPROFILE%\.ndev\nginx\conf\nginx.conf
  • Virtual Host Configs: %USERPROFILE%\.ndev\nginx\conf\ndev-vhosts\*.conf
  • FastCGI Worker Pools: Base port 13000 with 4 workers per PHP version (customizable in config.json).

Linux

  • Global Settings: ~/.ndev/config.toml
  • PHP Configuration: ~/.ndev/php/<version>/etc/php.ini
  • PHP Extensions: ~/.ndev/php/<version>/etc/conf.d/<ext>.ini
  • PHP-FPM Pool Config: ~/.ndev/php/<version>/etc/php-fpm.d/www.conf

License

MIT License. See LICENSE for more details.

Metadata

Release files for ndev-stack 0.3.13

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ndev-stack 0.3.13
File Size Uploaded Provenance Actions
ndev_stack-0.3.13.tar.gz 183.1 kB Without provenance Details for ndev_stack-0.3.13.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ndev-stack 0.3.13
File Interpreter ABI Platform Actions
ndev_stack-0.3.13-py3-none-any.whl Python 3 none any Details for ndev_stack-0.3.13-py3-none-any.whl

Total release size: 395.8 kB

Release files / ndev_stack-0.3.13.tar.gz

Download URL ndev_stack-0.3.13.tar.gz
Size 183.1 kB
Tags Source
SHA-256 checksum
How to use checksums
f28a8f5f3805d23df9d2ff5320c61dd51497c76aa604b40ae00e1538475071ac
BLAKE2b-256 checksum
How to use checksums
1f23b8b458fb8f8230bb0a9f9c246de820bbf9f2c48138cc039dabf4909c5680
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / ndev_stack-0.3.13-py3-none-any.whl

Download URL ndev_stack-0.3.13-py3-none-any.whl
Size 212.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
de52c582732c92256d5c5bb286cc4933fb6c8d1d4466359ec26b09c8326cd5bb
BLAKE2b-256 checksum
How to use checksums
391cc676ba34a76af071505ea65a1da814211fbcf288cf5dfeb76e376643ec25
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for ndev-stack 0.3.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page