Install & Compatibility
Where this runs
tested against v1.62.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 25.33s
py 3.11
✕ build_error
✓ 25.58s
py 3.9
✕ build_error
✓ 29.18s
299MB installed
● package 299MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Workspace
✓ from azureml.core import Workspace
Used to connect to your Azure ML workspace.
Experiment
✓ from azureml.core import Experiment
Used to create and manage ML experiments.
Environment
✓ from azureml.core import Environment
Used to define the reproducible Python environment for runs and deployments.
ScriptRunConfig
✓ from azureml.core import ScriptRunConfig
Encapsulates the script, compute target, and environment for a training run.
ComputeTarget
✓ from azureml.core.compute import ComputeTarget
✗ from azureml.core import ComputeTarget
ComputeTarget is typically imported from the `azureml.core.compute` submodule, not directly from `azureml.core`.
This quickstart demonstrates how to connect to an Azure ML Workspace, define a custom environment, create a compute target (or use 'local'), and submit a simple Python script as an experiment using `ScriptRunConfig` in Azure ML SDK v1. A `config.json` file in a `.azureml` subdirectory is the recommended way to connect to a workspace.
import os
from azureml.core import Workspace, Experiment, Environment, ScriptRunConfig
from azureml.core.compute import ComputeTarget, AmlCompute
from azureml.core.compute_target import ComputeTargetException
from azureml.core.conda_dependencies import CondaDependencies
# Create a dummy script file
with open('train_script.py', 'w') as f:
f.write("""
import argparse
import os
import time
print("Hello from Azure ML v1 training script!")
parser = argparse.ArgumentParser()
parser.add_argument('--arg1', type=str, default='default_value')
args = parser.parse_args()
print(f"Argument 1: {args.arg1}")
time.sleep(5) # Simulate work
print("Script finished.")
""")
# Create a dummy conda environment file
with open('conda_env.yml', 'w') as f:
f.write("""
name: my_env
dependencies:
- python=3.8
- pip:
- azureml-defaults
""")
# NOTE: For a real scenario, replace placeholder values and ensure a config.json is available
# Authenticate and connect to your workspace
try:
ws = Workspace.from_config(path='./.azureml', _file_name='config.json') # Reads from a local config.json
print(f"Connected to workspace {ws.name}")
except Exception as e:
print(f"Could not load workspace from config. Ensure .azureml/config.json exists or provide details manually: {e}")
# Fallback to manual connection (replace with your actual details)
subscription_id = os.environ.get('AZURE_SUBSCRIPTION_ID', 'YOUR_SUBSCRIPTION_ID')
resource_group = os.environ.get('AZURE_RESOURCE_GROUP', 'YOUR_RESOURCE_GROUP')
workspace_name = os.environ.get('AZURE_WORKSPACE_NAME', 'YOUR_WORKSPACE_NAME')
ws = Workspace(subscription_id, resource_group, workspace_name)
print(f"Connected to workspace {ws.name} via manual details.")
experiment_name = "my-first-v1-experiment"
experiment = Experiment(workspace=ws, name=experiment_name)
# Choose a name for your CPU cluster (or use 'local')
compute_name = "cpu-cluster"
compute_target = None
try:
compute_target = ComputeTarget(workspace=ws, name=compute_name)
print(f"Found existing compute target: {compute_name}")
except ComputeTargetException:
print(f"Creating a new compute target: {compute_name}")
compute_config = AmlCompute.provisioning_configuration(vm_size='STANDARD_DS1_V2', max_nodes=1)
compute_target = ComputeTarget.create(ws, compute_name, compute_config)
compute_target.wait_for_completion(show_output=True)
# Define the environment
env = Environment.from_conda_specification(name='my-custom-env', file_path='conda_env.yml')
# Create a ScriptRunConfig
src = ScriptRunConfig(
source_directory='.',
script='train_script.py',
compute_target=compute_target,
environment=env,
arguments=['--arg1', 'hello_from_run']
)
# Submit the run
run = experiment.submit(src)
print(f"Submitted run: {run.get_portal_url()}")
run.wait_for_completion(show_output=True)
print(f"Run completed with status: {run.status}")
Debug
Known issues
breakingAzure Machine Learning SDK v1 is officially deprecated as of March 31, 2025, with end of support on June 30, 2026. After this date, existing workflows may still run but will not receive technical support or updates, potentially exposing them to security risks or breaking changes.fixMigrate your workflows to the Azure Machine Learning Python SDK v2 (`azure-ai-ml`). This involves significant API changes; refer to the official migration guides.
affects: All versions of azureml-sdk (v1)
gotchaSDK v1 (`azureml-sdk`) and SDK v2 (`azure-ai-ml`) are incompatible and should generally not be installed in the same Python environment to avoid package clashes and confusion.fixUse separate Python environments for SDK v1 and SDK v2 projects. If mixed interaction with a single workspace is needed, ensure distinct environments for each SDK version.
affects: All versions when used with SDK v2
gotchaAuthentication to an Azure ML Workspace in v1 often relies on a `config.json` file (containing subscription ID, resource group, and workspace name) placed in a `.azureml` subdirectory or explicitly passed parameters. Without proper configuration, connection attempts will fail. Interactive authentication is also common for initial setup.fixEnsure a valid `config.json` file is present in the default search path (`.azureml/`) or specify the workspace details directly. For interactive authentication, follow the browser prompts. For automated scripts, consider service principal authentication.
affects: All v1 versions
deprecated`Estimator` classes, a common way to define training jobs in earlier v1 versions, are effectively superseded by `ScriptRunConfig` and later `Command` (in v2). While still functional in v1, `ScriptRunConfig` offers more flexibility.fixPrefer `ScriptRunConfig` for submitting training jobs in SDK v1. When migrating to SDK v2, `Command` jobs are the direct equivalent.
affects: Earlier v1 versions using Estimator
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azureml'
The `azureml-sdk` (or its core components like `azureml-core`) is not installed in the current Python environment, or a local Python file is incorrectly named `azureml.py`, shadowing the actual package.
fixEnsure the package is installed using `pip install azureml-sdk` or `pip install azureml-core`. If a local file is named `azureml.py`, rename it to avoid conflicts.
ModuleNotFoundError: No module named 'ruamel'
This error occurs when `azureml-defaults` (a dependency of `azureml-sdk`) fails to install `ruamel.yaml` correctly, often due to incompatibilities with `pip` versions greater than `20.1.1`.
fixPin the `pip` version to `20.1.1` before installing `azureml-sdk` or `azureml-defaults` by running `pip install pip==20.1.1` and then `pip install azureml-sdk`.
UserErrorException: Message: We could not find config.json
When using `Workspace.from_config()`, the SDK cannot find the `config.json` file containing the Azure Machine Learning workspace connection details in the current directory or the specified path.
fixPlace the `config.json` file (downloadable from your Azure ML workspace portal) in your working directory, provide the full path to the file, or connect to the workspace using explicit parameters: `from azureml.core import Workspace; ws = Workspace(subscription_id='<your-sub-id>', resource_group='<your-resource-group>', workspace_name='<your-workspace-name>')`.
azureml.exceptions.AuthenticationException / Authorization failed Error
Authentication to the Azure ML workspace fails due to incorrect or expired credentials, insufficient Azure RBAC permissions for the user or service principal, or a misconfigured authentication method.
fixFor interactive login, ensure you are logged into Azure CLI (`az login`). Verify that your user or service principal has appropriate Azure RBAC roles (e.g., 'Contributor', 'AzureML Data Scientist') on the workspace, resource group, or subscription. If using a service principal, confirm environment variables (`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`) are correctly set. In some older SDK versions, downgrading `PyJWT` to `1.7.1` resolved this.
ModuleNotFoundError: No module named 'azureml.train'
This usually indicates that a specific sub-package like `azureml-train` (or related modules like `azureml.train.hyperdrive`) is either not installed or the installed `azureml-sdk` version is too old to contain the required module.
fixInstall the full `azureml-sdk` or ensure specific sub-packages are included: `pip install azureml-sdk[train]` or `pip install azureml-train-core`. If the issue persists, ensure your `azureml-sdk` version is up-to-date or meets the minimum version requirement for the module you are trying to import.
Upgrade
Version history
1.62.0latest on PyPI · released Feb 25, 2026
Audit
Dependencies
No dependency data recorded yet.