Skip to main content

​
Quick Installation

ZenML requires Python 3.10 or higher. Install it using pip: 
pip install "zenml[server]"
The [server] extra includes components needed to run a local ZenML server. If you only need to connect to a remote server, use pip install zenml for a lighter installation.

​
System Requirements

​
Python Version Support

ZenML supports Python 3.10, 3.11, 3.12, and 3.13:
  • Python 3.10: Minimum supported version
  • Python 3.11: Recommended for best compatibility
  • Python 3.12: Fully supported
  • Python 3.13: Latest supported version
Python 3.9 and earlier are not supported. Python 3.14 support will be added in future releases.

​
Platform Support

  • Linux: Fully supported (Ubuntu, CentOS, Debian, etc.)
  • macOS: Fully supported (Intel and Apple Silicon)
  • Windows: Supported via WSL2 (native Windows support is experimental)

​
Installation Options

​
Local Development Setup

For local development with a self-contained server: 
# Install with local server capabilities
pip install "zenml[server]"

# Initialize ZenML repository in current directory
zenml init

# Start local server (includes web dashboard)
zenml login --local
This installs ZenML with:
  • SQLModel-based local database (SQLite by default)
  • FastAPI server for the dashboard
  • All core dependencies for pipeline execution
1

Install ZenML

Run pip install "zenml[server]" to install ZenML with server components.
2

Initialize Repository

Navigate to your project directory and run zenml init to create a .zen directory with configuration.
3

Start Server

Run zenml login --local to start a local server. This launches the dashboard at http://localhost:8237.
4

Verify Installation

Run zenml status to confirm everything is configured correctly.

​
Production Client Installation

For connecting to a deployed ZenML server: 
# Install minimal client
pip install zenml

# Connect to remote server
zenml login https://your-zenml-server.com --api-key YOUR_API_KEY

# Verify connection
zenml status

​
Optional Integrations

ZenML provides optional extras for specific integrations and use cases: 
# AWS integrations (S3, SageMaker, ECS, etc.)
pip install "zenml[connectors-aws,s3fs,sagemaker]"

# GCP integrations (GCS, Vertex AI, GKE, etc.)
pip install "zenml[connectors-gcp,gcsfs,vertex]"

# Azure integrations (Blob Storage, AzureML, AKS, etc.)
pip install "zenml[connectors-azure,adlfs,azureml]"
You can combine multiple extras: pip install "zenml[server,s3fs,mlflow,jupyter]"

​
Verification

After installation, verify everything works: 
# Check ZenML version
zenml version

# Output: ZenML version: 0.94.0

# Check installation status
zenml status

# Example output:
# ┏━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
# ┃ Property           │ Value                             ┃
# ┠────────────────────┼───────────────────────────────────┨
# ┃ ZenML version      │ 0.94.0                            ┃
# ┃ Store type         │ local                             ┃
# ┃ Database URL       │ sqlite:///~/.zen/local_store/...  ┃
# ┗━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

# List available stacks
zenml stack list

# Create and run a simple test pipeline
python -c "from zenml import step, pipeline
@step
def hello() -> str:
    return 'Hello ZenML!'
@pipeline
def test_pipeline():
    hello()
test_pipeline()"

​
Installation for Different Use Cases

​
Data Scientists (Local Experimentation)

# Full local setup with Jupyter support
pip install "zenml[server,jupyter]"
zenml init
zenml login --local

# Optional: Install experiment tracking
pip install "zenml[mlflow]"

​
ML Engineers (Production Pipelines)

# Client only - connect to team server
pip install zenml

# Add cloud integrations as needed
pip install "zenml[s3fs,connectors-aws]"

# Connect to production server
zenml login https://zenml.company.com --api-key $ZENML_API_KEY

​
Platform Teams (Server Deployment)

See the Deploying ZenML documentation for production server deployment options including:
  • Docker Compose deployment
  • Kubernetes Helm charts
  • Cloud-managed deployments (AWS, GCP, Azure)

​
Development Installation (From Source)

For contributing to ZenML or using the latest development features: 
# Clone repository
git clone https://github.com/zenml-io/zenml.git
cd zenml

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode with all dev dependencies
pip install -e ".[dev,server]"

# Or use uv for faster installation
uv pip install -e ".[dev,server]"

# Verify development installation
zenml version
Development installation includes testing tools, linting, type checking, and documentation generation dependencies. See pyproject.toml for the complete list.

​
Docker Installation

Run ZenML in a Docker container: 
# Pull the latest ZenML server image
docker pull zenmldocker/zenml:latest

# Run server container
docker run -d -p 8237:8237 \
  --name zenml-server \
  zenmldocker/zenml:latest

# Access dashboard at http://localhost:8237
For production Docker deployments, see the Docker deployment guide.

​
Environment Variables

Configure ZenML behavior with environment variables: 
# Logging and debugging
export ZENML_DEBUG=true
export ZENML_LOGGING_VERBOSITY=INFO

# Analytics (opt out if desired)
export ZENML_ANALYTICS_OPT_IN=false

# Dashboard behavior
export AUTO_OPEN_DASHBOARD=false

# Database configuration (for local server)
export ZENML_DEFAULT_PROJECT_NAME="my_project"
For a complete list of environment variables, see the configuration documentation.

​
Upgrading ZenML

Always backup your ZenML database before upgrading, especially in production environments.
# Upgrade to latest version
pip install --upgrade "zenml[server]"

# Upgrade to specific version
pip install --upgrade "zenml[server]==0.94.0"

# After upgrade, run database migrations
zenml migrate

# Verify upgrade
zenml version

​
Troubleshooting

​
Common Issues

This usually means ZenML wasn’t installed in the active Python environment.
# Check which Python you're using
which python
python --version

# Reinstall in correct environment
pip install "zenml[server]"
Another ZenML server or application is using the default port.
# Stop existing server
zenml down

# Or start server on different port
zenml login --local --port 8238
Database schema is out of sync with ZenML version.
# Run migrations
zenml migrate

# If migrations fail, you may need to backup and reinitialize
cp -r ~/.zen ~/.zen.backup
zenml clean
zenml init
Integration extras aren’t installed.
# Install required integration
pip install "zenml[mlflow]"  # for MLflow
pip install "zenml[s3fs]"    # for S3 artifact store

# Check installed integrations
zenml integration list

​
Getting Help

If you encounter issues:
  1. Check the troubleshooting guide
  2. Search GitHub issues
  3. Ask on Slack - 4,000+ community members
  4. Review system logs

​
Next Steps

Quickstart Tutorial

Build your first pipeline in 5 minutes

Core Concepts

Learn about pipelines, steps, and stacks

Integrations

Connect ZenML to your existing tools

Deploy to Production

Set up a production ZenML server

Build docs developers (and LLMs) love

Get started for freeTalk to us