Skip to main content
The zenml init command initializes a ZenML repository in your current directory, setting up the necessary configuration and resource management tools.

​
Basic Usage

zenml init
This creates a hidden .zen folder in your current directory containing ZenML configuration and metadata.

​
Command Options

​
Custom Path

Initialize ZenML in a specific directory: 
zenml init --path /path/to/dir

​
Using Project Templates

Bootstrap your project with a ready-to-use template: 
zenml init --template <template_name>
Available templates:
  • starter - Basic ZenML project structure
  • e2e_batch - End-to-end batch inference pipeline
  • nlp - Natural language processing template
  • llm_finetuning - LLM fine-tuning template

​
Template with Defaults

Skip interactive prompts and use default values: 
zenml init --template starter --template-with-defaults

​
Custom Template URL

Use a custom Copier template from GitHub: 
zenml init --template gh:your-org/your-template

​
Specify Template Version

Use a specific version tag: 
zenml init --template gh:your-org/your-template --template-tag v1.0.0

​
Complete Option Reference

OptionTypeDescription
--pathPathDirectory path where ZenML should be initialized (defaults to current directory)
--templateStringName or URL of a ZenML project template (e.g., starter, e2e_batch, or gh:owner/repo)
--template-tagStringOptional version tag for custom template URLs (ignored for built-in templates)
--template-with-defaultsFlagUse template default values without interactive prompts

​
Examples

​
Initialize in Current Directory

cd my-ml-project
zenml init
Output: 
ZenML repository initialized at /Users/username/my-ml-project

​
Initialize with Starter Template

zenml init --template starter
You’ll be prompted for:
  • Project name
  • Project description
  • Author information
  • Other template-specific options

​
Quick Template Setup (No Prompts)

zenml init --template e2e_batch --template-with-defaults
This creates a complete project structure with default values, perfect for quick experimentation.

​
Initialize in Specific Directory

zenml init --path ~/projects/new-ml-project

​
Use Custom GitHub Template

zenml init --template gh:my-org/custom-zenml-template --template-tag v2.1.0

​
What Gets Created

When you run zenml init, ZenML creates:
  1. .zen directory - Hidden folder containing:
    • Configuration files
    • Local metadata database (if using local mode)
    • Cache files
  2. Template files (if using --template):
    • Python pipeline definitions
    • Configuration files
    • Example notebooks
    • README and documentation
    • Requirements files

​
Template Requirements

To use project templates, you need the templates extra: 
pip install 'zenml[templates]'
Without this, you’ll see an error message: 
You need to install the ZenML project template requirements to use templates.
Please run `pip install 'zenml[templates]'` and try again.

​
When to Use zenml init

Use zenml init when:

Starting a New Project

Initialize ZenML in a new ML project to enable pipeline tracking and stack management.

Using Project Templates

Bootstrap a project with best practices and example code using built-in templates.

Setting Up Team Projects

Establish a shared project structure with standardized configurations.

Exploring ZenML

Quickly set up example projects to learn ZenML features.

​
Common Workflows

​
Initialize and Connect to Server

# Initialize repository
zenml init

# Connect to ZenML Pro
zenml login

# Verify connection
zenml status

​
Start with Template

# Create project from template
zenml init --template starter --template-with-defaults

# Install dependencies
pip install -r requirements.txt

# Run example pipeline
python run.py

​
Initialize Existing Project

# Navigate to existing project
cd my-existing-ml-project

# Initialize ZenML (no template)
zenml init

# Register existing pipelines
zenml pipeline register my_module.training_pipeline

​
Exploring Templates

Before initializing, you can explore templates on GitHub:

​
Troubleshooting

​
Already Initialized

If you run zenml init in a directory that’s already initialized, you’ll see an error. To reinitialize: 
# Remove existing .zen folder
rm -rf .zen

# Initialize again
zenml init

​
Template Installation Issues

If template creation fails:
  1. Ensure you have zenml[templates] installed
  2. Check your internet connection (templates are fetched from GitHub)
  3. Verify the template name or URL is correct

​
Next Steps

After initializing your repository:

Login to Server

Connect to ZenML Pro or self-hosted server

Configure Stack

Set up your MLOps stack components

Install Integrations

Add integrations for cloud providers and tools

Run Pipeline

Execute your first pipeline

Build docs developers (and LLMs) love

Get started for freeTalk to us