Azure ML Defaults

Common errors

• ModuleNotFoundError: No module named 'azureml.core'

  cause The `azureml-core` package (or the `azureml-defaults` metapackage which includes it) is not installed in the current Python environment.
  fix `pip install azureml-defaults` or `pip install azureml-core`

• azureml.core.authentication.AuthenticationException: No authentication mechanisms are currently available.

  cause The Azure ML SDK failed to find valid credentials to connect to your workspace. This often happens locally if you haven't logged in via Azure CLI or provided a `config.json`.
  fix Run `az login` in your terminal, or download `config.json` from your Azure ML workspace (Azure Portal -> Overview -> Download config.json) and place it in your script's directory or a parent directory.

• Cannot uninstall 'azureml-core'. It is a distutils installed project and thus we cannot accurately determine which files belong to it which would be needed for a full uninstall.

  cause This error often occurs in environments where `azureml-core` (or other `azureml-*` packages) were installed outside of `pip`'s normal tracking, or when `pip` tries to downgrade a package installed by `conda` or another method.
  fix If in a conda environment, try `conda uninstall azureml-core`. If you need to force-install a specific version, use `pip install azureml-core==X.Y.Z --ignore-installed` (use with caution as it can break dependencies) or preferably, use a fresh virtual environment.

• AttributeError: 'NoneType' object has no attribute 'get'

  cause This typically happens when trying to access `Run.get_context()` outside of an active Azure ML experiment run. `Run.get_context()` returns `None` if not called within a submitted script on an Azure ML compute.
  fix Ensure your script is submitted as part of an Azure ML experiment run (e.g., via `ScriptRunConfig` or `Estimator`). For local testing, mock the `Run` object or handle the `None` case explicitly.

Warnings

• gotcha azureml-defaults is a metapackage; it doesn't contain user-facing classes directly. Users should import from specific sub-packages like `azureml.core`, `azureml.data`, etc. Its role is to ensure these sub-packages are installed at compatible versions.
  Fix: Always import classes from their specific sub-package (e.g., `from azureml.core import Workspace`), not from `azureml_defaults`.
• breaking Mixing `pip install azureml-defaults` with individual `pip install azureml-<package-name>` commands, especially across different versions, can lead to dependency conflicts or unexpected behavior. The `azureml-defaults` package pins versions for consistency.
  Fix: Prefer installing *only* `azureml-defaults` or *only* specific `azureml-*` packages but not both, unless you carefully manage versions. Use a clean virtual environment for each project or to test upgrades.
• gotcha Installing `azureml-defaults` can be quite large, pulling in many dependencies. This can consume significant disk space and lead to slower environment creation, especially in constrained environments or CI/CD pipelines.
  Fix: If you only need a specific subset of the SDK (e.g., just `azureml-core` for deployment), consider installing only those specific packages rather than the entire `azureml-defaults` metapackage. However, be mindful of potential version conflicts.
• gotcha Authentication mechanisms for local development (`Workspace.from_config()`) often require `config.json` or prior `az login`. In compute targets, authentication is typically handled automatically through managed identity or service principal.
  Fix: For local development, ensure `az login` is performed or a `config.json` is present. For automated environments, use `ServicePrincipalAuthentication` or `ManagedIdentityAuthentication`.

Install

• pip install azureml-defaults Install the default Azure ML SDK

Imports

• Workspace
  wrong:

  from azureml_defaults import Workspace

  correct:

  from azureml.core import Workspace

  azureml-defaults is a metapackage; user-facing classes are in sub-packages like azureml.core.
• Experiment
  wrong:

  from azureml_defaults import Experiment

  correct:

  from azureml.core import Experiment

  azureml-defaults is a metapackage; user-facing classes are in sub-packages like azureml.core.
• Run

  from azureml.core import Run

  Used to get the current experiment run context, especially within Azure ML compute targets.

Quickstart

This quickstart demonstrates how to connect to an existing Azure Machine Learning Workspace and initiate a simple experiment run using the `azureml.core` components that `azureml-defaults` ensures are installed. It highlights the importance of authentication and workspace configuration (via `config.json` or environment variables) for local development.

import os
from azureml.core import Workspace, Experiment, Environment

# NOTE: For local execution, ensure you have a config.json or environment variables.
# You can create a config.json by connecting to your workspace in Azure portal
# and downloading the config.json file.

# Example for connecting to an existing workspace
try:
    ws = Workspace.from_config() # Looks for config.json in current directory or parent directories
    print(f"Workspace name: {ws.name}, Resource Group: {ws.resource_group}, Location: {ws.location}")

    # Create a simple experiment
    exp = Experiment(workspace=ws, name="my-first-azureml-experiment")
    print(f"Experiment name: {exp.name}")

    # Start a run (this example won't submit to a remote compute, just demonstrates API)
    with exp.start_logging() as run:
        run.log('hello_world', 'true')
        print("Run logged 'hello_world'")
        print(f"Run ID: {run.id}")

except Exception as e:
    print(f"Error connecting to workspace or running experiment: {e}")
    print("Please ensure you are authenticated (e.g., 'az login') or have a valid config.json.")
    print("You might need to set AZUREML_CR_NAME, AZUREML_CR_RESOURCE_GROUP, AZUREML_CR_SUBSCRIPTION_ID in environment variables.")

# Example of creating a workspace (requires Azure CLI login and permissions)
# from azureml.core.authentication import AzureCliAuthentication
# try:
#     cli_auth = AzureCliAuthentication()
#     ws = Workspace.create(
#         name='myworkspacename',
#         subscription_id=os.environ.get('AZURE_SUBSCRIPTION_ID', 'YOUR_SUB_ID'),
#         resource_group='myresourcegroup',
#         create_resource_group=True,
#         location='eastus',
#         auth=cli_auth
#     )
#     print(f"Created workspace: {ws.name}")
# except Exception as e:
#     print(f"Could not create workspace: {e}")