02: Create Environment

Concepts covered:

  • What Hatch environments are and how they work
  • Python environment integration via conda/mamba
  • Environment metadata and configuration storage

Skills you will practice:

  • Creating a new Hatch environment
  • Creating environments with Python integration
  • Managing environment options and configurations

This article covers creating your first Hatch environment for managing MCP server packages.

Step 1: Create a Basic Environment

Create a simple Hatch environment without Python integration:

hatch env create my_first_env --description "My first Hatch environment" --no-python

This creates an environment that can manage Hatch packages but doesn’t include a Python environment.

[!NOTE] Environment names must be alphanumeric and can contain underscores.

Step 2: Create an Environment with Python Integration

For most use cases, you’ll want Python integration for running MCP servers:

hatch env create my_python_env --description "Environment with Python support" --python-version 3.11

This command:

  • Creates a Hatch environment named my_python_env
  • Sets up a Python 3.11 environment using conda/mamba
  • Installs the hatch_mcp_server wrapper by default

Understanding the Options

  • --python-version - Specifies the Python version (e.g., 3.11, 3.12)
  • --no-python - Skips Python environment creation
  • --no-hatch-mcp-server - Skips installation of the hatch_mcp_server wrapper
  • --hatch_mcp_server_tag - Specifies a git tag/branch for the wrapper (e.g., ‘dev’, ‘v0.1.0’)

Step 3: Verify Environment Creation

List your environments to confirm they were created:

hatch env list

You should see output similar to:

Available environments:
  my_first_env - My first Hatch environment
    Python: Not configured
  my_python_env - Environment with Python support
    Python: 3.11.x (conda: my_python_env)

Python Environment Manager:
  Conda executable: /path/to/conda
  Mamba executable: /path/to/mamba
  Preferred manager: mamba

Exercise: Initialize a Python environment inside my_first_env. Try both initializing without hatch_mcp_server wrapper and adding it afterwards. Hint: Use hatch env python --help to explore available Python subcommands and flags.

Solution ```bash # Initialize a Python environment inside my_first_env hatch env python init --hatch_env my_first_env --no-hatch-mcp-server # Verify Python environment hatch env python info --hatch_env my_first_env # hatch_mcp_server should not appear in the list of packages # Add hatch_mcp_server wrapper hatch env python add-hatch-mcp --hatch_env my_first_env # Verify again hatch env python info --hatch_env my_first_env # hatch_mcp_server should now appear in the list of packages ```

In most use cases, you’ll want to create environments with Python integration and the hatch_mcp_server wrapper. However, Hatch provides flexibility to customize your environments as needed.

Previous: Installation
Next: Install Package