Migration from Python

This guide helps you migrate from the Python version of nyl to the Rust version.

Compatibility Status

Phase 1: ✅ Compatible

The Rust version in Phase 1 is compatible with existing Python nyl projects for:

Configuration loading (YAML/JSON)
Project structure
Component creation
Configuration validation

Phase 2+: 🚧 In Progress

Full compatibility for template rendering, Helm integration, and Kubernetes operations will be available in later phases.

Installation

Uninstall Python nyl (Optional)

pip uninstall nyl

Install Rust nyl

cd nyl-rs
cargo install --path .

Or use the pre-built binary from releases.

Configuration

No Changes Needed

Your existing nyl-project.yaml files work as-is:

settings:
  generate_applysets: false
  on_lookup_failure: Error
  components_path: components
  search_path:
    - .
    - lib

TOML Support

TOML support (nyl-project.toml) is planned for Phase 2 or later. For now, use YAML or JSON.

Unknown Fields

The Rust version will warn about unknown fields in the configuration but will not fail. This provides forward compatibility.

Commands

Phase 1 Commands

Command	Python	Rust	Status
`new project`	✅	✅	Compatible
`new component`	✅	✅	Compatible
`validate`	✅	✅	Compatible

Phase 2+ Commands

Command	Python	Rust	Status
`render`	✅	🚧	Phase 3
`diff`	✅	🚧	Phase 4
`apply`	✅	🚧	Phase 4

Validation

Run validation to ensure compatibility:

nyl validate

If validation passes, your project is compatible with nyl-rs.

Behavior Differences

Path Resolution

Both versions resolve relative paths the same way:

Relative to the configuration file’s parent directory
Absolute paths remain unchanged

Error Messages

Error messages in Rust nyl may be more concise but provide the same information.

Performance

The Rust version is significantly faster:

Configuration loading: ~5-10x faster
File operations: ~2-3x faster
Overall: ~5-10x faster (goal)

Migration Checklist

Install Rust nyl
Run nyl validate on existing projects
Test nyl new component for creating new components
Verify configuration loading works
Update CI/CD pipelines to use new binary
Wait for Phase 2+ for full feature parity

Feature Comparison

Phase 1 Features

Feature	Python	Rust
YAML config	✅	✅
JSON config	✅	✅
TOML config	✅	🚧 Phase 2
Config validation	✅	✅
Project scaffolding	✅	✅
Component scaffolding	✅	✅
File discovery	✅	✅
Verbose logging	✅	✅

Phase 2+ Features

Feature	Python	Rust
Component discovery	✅	🚧 Phase 2
Helm integration	✅	🚧 Phase 2
Template rendering	✅	🚧 Phase 3
Profile support	✅	🚧 Phase 2
Secret providers	✅	🚧 Phase 2
Kubernetes apply	✅	🚧 Phase 4
Diff command	✅	🚧 Phase 4

Breaking Changes

None in Phase 1

Phase 1 maintains full backward compatibility with Python nyl.

Future Phases

Breaking changes (if any) will be documented when they are introduced. The goal is to maintain compatibility wherever possible.

Getting Help

If you encounter issues during migration:

Run nyl validate --strict to identify problems
Check the Configuration documentation
Review command documentation for syntax changes
File an issue on GitHub

Performance Comparison

Benchmarks show significant performance improvements:

Operation	Python	Rust	Improvement
Config load	5ms	0.5ms	10x
Validation	10ms	1ms	10x
Project creation	50ms	5ms	10x

Binary size: 2.0MB (Rust) vs ~50MB (Python with dependencies)

Rollback Plan

If you need to rollback to Python nyl:

# Uninstall Rust nyl
cargo uninstall nyl

# Reinstall Python nyl
pip install nyl

Your project files remain unchanged and will work with either version.

Keyboard shortcuts

Nyl Documentation