CLI Reference - Metaflow Netflix Extensions

Conda v2 provides a comprehensive CLI for managing environments outside of your flow code. All commands are available under metaflow environment.

Global Options

These options apply to all metaflow environment commands:

metaflow environment [OPTIONS] COMMAND [ARGS]

—quiet / —no-quiet

Default: False Suppress unnecessary messages. Useful for scripting.

metaflow environment --quiet show my_env

—metadata

Default: service
Choices: local, service Metadata service type to use.

metaflow environment --metadata local show my_env

—datastore

Default: s3
Choices: s3, local, azure, gs Datastore type for environment caching.

metaflow environment --datastore azure show my_env

—environment

Default: conda
Choices: conda Type of environment to manage (currently only conda is supported).

—conda-root

Root path for Conda cached information. Overrides METAFLOW_CONDA_S3ROOT (or equivalent for other datastores).

metaflow environment --conda-root s3://my-bucket/conda resolve -r requirements.txt

resolve

Resolve dependencies into a fully specified environment.

metaflow environment resolve [OPTIONS]

Options

—alias

Type: String (multiple allowed)
Default: None Alias the resolved environment. Can specify multiple times for multiple aliases.

metaflow environment resolve \
  --alias my_team/my_env:v1 \
  --alias my_team/my_env:latest \
  -r requirements.txt

—force / —no-force

Default: False Force resolution of already resolved environments.

metaflow environment resolve --force -r requirements.txt

—local-only / —non-local

Default: False Only look locally for “using” environments (don’t fetch from remote).

metaflow environment resolve --local-only --using my_env:v1 -r extra.txt

—dry-run / —no-dry-run

Default: False Only resolve, don’t download, cache, persist, or alias anything.

metaflow environment resolve --dry-run -r requirements.txt

—set-default / —no-set-default

Default: True Set the resolved environment as the default for this requirement ID.

metaflow environment resolve --no-set-default -r requirements.txt

—arch

Type: String (multiple allowed)
Default: Current architecture Architecture(s) to resolve for. Can specify multiple times.

metaflow environment resolve \
  --arch linux-64 \
  --arch osx-arm64 \
  -r requirements.txt

—python

Type: String
Default: Current Python version Python version constraint.

metaflow environment resolve --python ">=3.8,<3.9" -r requirements.txt

-r, —requirement

Type: File path Get environment definition from a requirements.txt file (pip format).

metaflow environment resolve -r requirements.txt

-f, —file

Type: File path Get environment definition from an environment.yml file (conda format).

metaflow environment resolve -f environment.yml

-p, —pyproject

Type: File path Get environment definition from a pyproject.toml file (poetry format).

metaflow environment resolve -p pyproject.toml

—using-pathspec

Type: String Create environment starting with the environment from the specified pathspec.

metaflow environment resolve \
  --using-pathspec MyFlow/123/train \
  -r additional_requirements.txt

—using

Type: String Create environment starting with the referenced environment.

metaflow environment resolve \
  --using my_team/base_env:v1 \
  -r additional_requirements.txt

—from-pathspec

Type: String Create environment by cloning requirements from the specified pathspec.

metaflow environment resolve \
  --from-pathspec MyFlow/123/train \
  --arch osx-arm64

—from

Type: String Create environment by cloning requirements from the referenced environment.

metaflow environment resolve \
  --from my_team/my_env:v1 \
  --arch linux-64

Examples

Basic Resolution
With Alias
Multi-Architecture
Extending

Resolve from requirements file:

metaflow environment resolve \
  --python ">=3.8,<3.9" \
  -r requirements.txt

Resolve and create named environment:

metaflow environment resolve \
  --alias my_team/my_env:v1 \
  --python ">=3.8,<3.9" \
  -r requirements.txt

Resolve for multiple architectures:

metaflow environment resolve \
  --arch linux-64 \
  --arch osx-arm64 \
  --python ">=3.8,<3.9" \
  -r requirements.txt

Extend an existing environment:

metaflow environment resolve \
  --using my_team/base:v1 \
  --alias my_team/extended:v1 \
  -r extra_requirements.txt

create

Create a local Conda environment from a resolved environment.

metaflow environment create [OPTIONS] ENV_NAME

Arguments

ENV_NAME

Required Environment identifier. Can be:

A pathspec: MyFlow/123/train (with --pathspec flag)
A partial hash (req_id): 42a4ed94b63f12e1fe9dd29de21bf9ec6e271b1c
A full hash: 42a4ed94b63f12e1fe9dd29de21bf9ec6e271b1c:a3b104c4ce2215351a2b94076ef7827de3ad890a
An environment name: my_team/my_env:v1

Options

—name

Type: String
Default: Auto-generated Name for the local environment.

metaflow environment create --name myenv my_team/my_env:v1

—local-only / —non-local

Default: False Only create if environment is known locally (don’t fetch from remote).

metaflow environment create --local-only --name myenv my_team/my_env:v1

—force / —no-force

Default: False Recreate the environment if it exists. Also remove --into-dir if it exists.

metaflow environment create --force --name myenv my_team/my_env:v1

—strict / —no-strict

Default: True Fail if cannot install the original Metaflow environment.

metaflow environment create --no-strict --name myenv my_team/my_env:v1

—into-dir

Type: Directory path Download the step’s code package into this directory (for pathspecs).

metaflow environment create \
  --pathspec \
  --into-dir ~/debug \
  MyFlow/123/train

—install-notebook / —no-install-notebook

Default: False Install the environment as a Jupyter kernel. Requires --name.

metaflow environment create \
  --name myenv \
  --install-notebook \
  my_team/my_env:v1

—pathspec

Default: False The environment name is a pathspec.

metaflow environment create --pathspec MyFlow/123/train

Examples

From Named Env
From Pathspec
With Jupyter

Create from a named environment:

metaflow environment create \
  --name myenv \
  my_team/my_env:v1

Activate:

conda activate myenv

Create from a flow step:

metaflow environment create \
  --pathspec \
  --name debug_env \
  --into-dir ~/debug \
  MyFlow/123/train

Create with Jupyter kernel:

metaflow environment create \
  --name myenv \
  --install-notebook \
  my_team/my_env:v1

Then select “Metaflow my_team/my_env:v1” kernel in Jupyter.

When using --into-dir with a pathspec, the code package is downloaded and a metaflow_setup.sh script is created to set up environment variables.

show

Show information about an environment.

metaflow environment show [OPTIONS] ENVS...

Arguments

ENVS

Required (one or more) Environment identifier(s) to show.

Options

—local-only / —non-local

Default: False Only resolve using local information (don’t fetch from remote).

metaflow environment show --local-only my_team/my_env:v1

—arch

Default: Current architecture Show environment for this architecture.

metaflow environment show --arch linux-64 my_team/my_env:v1

—pathspec

Default: False The environments given are pathspecs.

metaflow environment show --pathspec MyFlow/123/train

Examples

Named Environment
Pathspec
Multiple
Different Arch

metaflow environment show my_team/my_env:v1

metaflow environment show --pathspec MyFlow/123/train

metaflow environment show my_team/env1:v1 my_team/env2:v1

metaflow environment show --arch osx-arm64 my_team/my_env:v1

Output

Shows:

Environment type (conda-only, pypi-only, mixed)
Full hash (req_id:full_id)
Architecture
Resolution date and user
Local presence
User-requested packages
All installed packages

get

Fetch an environment from remote storage to local cache.

metaflow environment get [OPTIONS] SOURCE_ENV

Arguments

SOURCE_ENV

Required Environment identifier to fetch.

Options

—default / —no-default

Default: True Set the downloaded environment as default for its requirement ID.

metaflow environment get --no-default my_team/my_env:v1

—arch

Type: String
Default: Current architecture Request this architecture.

metaflow environment get --arch linux-64 my_team/my_env:v1

—pathspec

Default: False The environment name is a pathspec.

metaflow environment get --pathspec MyFlow/123/train

Examples

Fetch Named
Fetch Pathspec
Different Arch

metaflow environment get my_team/my_env:v1

metaflow environment get --pathspec MyFlow/123/train

metaflow environment get --arch linux-64 my_team/my_env:v1

This command downloads the environment definition from remote storage and adds it to your local cache. It does not create the actual Conda environment - use create for that.

alias

Alias an existing environment with a new name.

metaflow environment alias [OPTIONS] SOURCE_ENV ALIAS

Arguments

SOURCE_ENV

Required Source environment identifier.

ALIAS

Required New alias name.

Options

—local-only / —non-local

Default: False Only resolve source environment using local information.

metaflow environment alias --local-only old_name new_name:v2

—pathspec

Default: False The source environment is a pathspec.

metaflow environment alias --pathspec MyFlow/123/train my_team/my_env:v1

Examples

Alias Hash
Alias Pathspec
Promote Candidate

metaflow environment alias \
  42a4ed94b63f12e1fe9dd29de21bf9ec6e271b1c \
  my_team/my_env:v1

metaflow environment alias \
  --pathspec \
  MyFlow/123/train \
  my_team/training_env:v1

metaflow environment alias \
  my_team/my_env:candidate \
  my_team/my_env:stable

Flow-Specific Commands

When using python myflow.py --environment=conda environment, you get flow-specific environment commands:

Resolve Flow Environments

python myflow.py --environment=conda environment resolve [OPTIONS]

Resolves all environments defined in the flow. Options: Same as metaflow environment resolve except no -r, -f, or -p options.

Example

python myflow.py --environment=conda environment resolve --force

Debugging and Inspection

View All Packages in an Environment

metaflow environment show my_team/my_env:v1 | grep "Packages installed"

Check if Environment Exists Locally

metaflow environment show --local-only my_team/my_env:v1

Find Which Steps Use an Environment

metaflow environment show --pathspec MyFlow/123/train
metaflow environment show --pathspec MyFlow/123/predict

Compare Two Environments

metaflow environment show my_team/my_env:v1 > env_v1.txt
metaflow environment show my_team/my_env:v2 > env_v2.txt
diff env_v1.txt env_v2.txt

Scripting with —quiet

Use --quiet for machine-readable output:

# Get environment hash
ENV_HASH=$(metaflow environment --quiet show my_team/my_env:v1)

# Parse output programmatically
metaflow environment --quiet show my_team/my_env:v1 | while read line; do
  echo "Processing: $line"
done

Get Started

Conda v2

Debug Extension

Guides

​Global Options

​—quiet / —no-quiet

​—metadata

​—datastore

​—environment

​—conda-root

​resolve

​Options

​—alias

​—force / —no-force

​—local-only / —non-local

​—dry-run / —no-dry-run

​—set-default / —no-set-default

​—arch

​—python

​-r, —requirement

​-f, —file

​-p, —pyproject

​—using-pathspec

​—using

​—from-pathspec

​—from

​Examples

​create

​Arguments

​ENV_NAME

​Options

​—name

​—local-only / —non-local

​—force / —no-force

​—strict / —no-strict

​—into-dir

​—install-notebook / —no-install-notebook

​—pathspec

​Examples

​show

​Arguments

​ENVS

​Options

​—local-only / —non-local

​—arch

​—pathspec

​Examples

​Output

​get

​Arguments

​SOURCE_ENV

​Options

​—default / —no-default

​—arch

​—pathspec

​Examples

​alias

​Arguments

​SOURCE_ENV

​ALIAS

​Options

​—local-only / —non-local

​—pathspec

​Examples

​Flow-Specific Commands

​Resolve Flow Environments

​Example

​Debugging and Inspection

​View All Packages in an Environment

​Check if Environment Exists Locally

​Find Which Steps Use an Environment

​Compare Two Environments

​Scripting with —quiet

​Next Steps

Configuration

Troubleshooting

Build docs developers (and LLMs) love

Global Options

—quiet / —no-quiet

—metadata

—datastore

—environment

—conda-root

resolve

Options

—alias

—force / —no-force

—local-only / —non-local

—dry-run / —no-dry-run

—set-default / —no-set-default

—arch

—python

-r, —requirement

-f, —file

-p, —pyproject

—using-pathspec

—using

—from-pathspec

—from

Examples

create

Arguments

ENV_NAME

Options

—name

—local-only / —non-local

—force / —no-force

—strict / —no-strict

—into-dir

—install-notebook / —no-install-notebook

—pathspec

Examples

show

Arguments

ENVS

Options

—local-only / —non-local

—arch

—pathspec

Examples

Output

get

Arguments

SOURCE_ENV

Options

—default / —no-default

—arch

—pathspec

Examples

alias

Arguments

SOURCE_ENV

ALIAS

Options

—local-only / —non-local

—pathspec

Examples

Flow-Specific Commands

Resolve Flow Environments

Example

Debugging and Inspection

View All Packages in an Environment

Check if Environment Exists Locally

Find Which Steps Use an Environment

Compare Two Environments

Scripting with —quiet

Next Steps