Setting Up a Conda Environment on Windows vs Linux for AI-For-Beginners

The AI-For-Beginners repository uses a single OS-agnostic environment.yml file that automatically resolves platform-specific dependencies, though shell activation commands and directory structures differ between Windows and Linux.

The microsoft/AI-For-Beginners curriculum ships with a ready-made Conda environment containing all required Python packages—including TensorFlow, PyTorch, Keras, and OpenCV—defined in the top-level environment.yml. While Conda handles cross-platform package resolution automatically, understanding the shell-level differences when setting up a Conda environment on Windows vs Linux prevents activation errors and ensures the Jupyter kernel registers correctly on your native OS.

The Cross-Platform Foundation

The environment definition lives at the repository root in environment.yml, which pins exact versions such as tensorflow==2.17.0 and numpy==1.26. According to the source code analysis of AGENTS.md, this file is OS-agnostic—Conda reads the dependency list and pulls the correct binary wheels for Windows, Linux, or macOS automatically. No modifications to the file are required regardless of your operating system.

Creation is identical on all platforms:

# From the repository root

conda env create --name ai4beg --file environment.yml

Platform-Specific Activation Workflows

Once created, the environment must be activated using shell-specific commands. The underlying Python interpreter and package paths are managed by Conda, but the activation syntax and directory structures vary.

Linux and macOS

On Bash or Zsh shells, activation uses the standard Conda command:

conda activate ai4beg

After activation, the environment's executables reside in bin/ within the Conda installation directory. This follows standard Unix filesystem conventions.

Windows PowerShell and Command Prompt

Windows uses the same activation command:

conda activate ai4beg

However, the environment's executables live in Scripts\ rather than bin/. If you receive a "conda is not recognized" error, ensure the Conda Scripts directory was added to your system PATH during installation. PowerShell users may need to run as administrator or adjust execution policies, while Command Prompt (cmd) requires the Anaconda Prompt for guaranteed access.

Jupyter Kernel Registration

Registering the kernel for the curriculum notebooks uses a unified command across all platforms, but it must be executed after activating the environment:

python -m ipykernel install --user --name ai4beg

This command installs the kernel specification in your user profile, making the ai4beg environment available in Jupyter Lab regardless of OS. Launch the notebooks with:

jupyter lab

VS Code Integration Differences

VS Code automatically detects the ai4beg environment once activated. On Linux, the integrated terminal recognizes the active Conda context immediately. On Windows, you may need to reload the VS Code window (Developer: Reload Window) after activation for the Python interpreter selector to populate correctly.

Troubleshooting Platform-Specific Issues

• Windows: If conda activate fails in PowerShell, run conda init powershell once to enable shell integration. Ensure you are not using Git Bash without Conda initialization, as it may not inherit Windows PATH variables correctly.
• Linux: If you encounter "Permission denied" errors or the conda command is unavailable in new terminals, run conda init bash (or zsh if applicable) to configure shell auto-activation.

Summary

• The environment.yml file at the repository root works identically on Windows and Linux without modifications.
• Use conda activate ai4beg on both platforms, but note that Windows stores executables in Scripts\ while Linux uses bin/.
• Register the Jupyter kernel using python -m ipykernel install --user --name ai4beg after activation on any OS.
• Windows users may need to reload VS Code after activation; Linux detection is typically automatic.
• Run conda init <shell_name> if the conda command is unrecognized in fresh terminal sessions.

Frequently Asked Questions

Do I need different environment.yml files for Windows and Linux?

No. The environment.yml in the AI-For-Beginners repository root is platform-agnostic. Conda resolves the correct binary dependencies for your operating system automatically when you run conda env create.

Why does Windows use a Scripts folder instead of bin?

Windows Conda environments place executables in envs/ai4beg/Scripts\ rather than envs/ai4beg/bin/ due to Windows filesystem conventions. This affects manual path configuration but does not change the conda activate workflow.

Can I use Git Bash on Windows for these commands?

Yes, Git Bash behaves like a Linux shell and accepts conda activate ai4beg. However, ensure Conda is initialized for Git Bash using conda init bash, or use the Anaconda Prompt to avoid PATH-related issues.

How do I verify the environment activated correctly?

Run which python (Linux/macOS) or where python (Windows) after activation. The path should point to the ai4beg environment directory. You can also check conda env list to see the asterisk (*) next to the active environment name.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}