Skip to content

Commit 154e415

Browse files
CopilotIEvangelist
Copilot
and
IEvangelist
authored
Add WSL-specific Podman documentation and troubleshooting guide (#4190)
* Initial plan * Add WSL-specific Podman documentation and troubleshooting guide Co-authored-by: IEvangelist <[email protected]> * Fix list numbering and punctuation in Podman WSL troubleshooting guide Co-authored-by: IEvangelist <[email protected]> * Add TOC entry and restructure Podman WSL troubleshooting guide Co-authored-by: IEvangelist <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: IEvangelist <[email protected]>
1 parent 69cbbfe commit 154e415

File tree

4 files changed

+128
-0
lines changed

4 files changed

+128
-0
lines changed

‎docs/fundamentals/setup-tooling.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,41 @@ For more information, see [Install Podman on Windows](https://podman.io/docs/ins
133133

134134
---
135135

136+
### WSL (Windows Subsystem for Linux) considerations
137+
138+
When using Podman with WSL, ensure that the `podman` executable is available in your `PATH` and not just defined as a shell alias. .NET Aspire resolves container runtimes by searching for the executable in the system PATH, and shell aliases aren't recognized during this process.
139+
140+
**Common issues and solutions:**
141+
142+
- **Podman installed in a separate WSL distribution**: If Podman is installed in a different WSL distribution than your .NET Aspire application, the `podman` command might not be available in your current distribution's PATH.
143+
144+
**Solution**: Install Podman directly in the WSL distribution where you're running your .NET Aspire application, or create a symbolic link to the Podman executable in a directory that's in your PATH (such as `/usr/local/bin`).
145+
146+
- **Using shell aliases**: If you have a shell alias like `alias podman='podman-remote-static-linux_amd64'` in your `~/.bash_aliases` or similar file, .NET Aspire won't be able to find the container runtime.
147+
148+
**Solution**: Instead of using an alias, create a symbolic link or add the directory containing the Podman executable to your PATH:
149+
150+
```bash
151+
# Option 1: Create a symbolic link
152+
sudo ln -s /path/to/podman-remote-static-linux_amd64 /usr/local/bin/podman
153+
154+
# Option 2: Add to PATH in your shell profile
155+
echo 'export PATH="/path/to/podman/directory:$PATH"' >> ~/.bashrc
156+
source ~/.bashrc
157+
```
158+
159+
**Verify your setup**: You can verify that Podman is correctly configured by running:
160+
161+
```bash
162+
which podman
163+
podman --version
164+
```
165+
166+
Both commands should succeed and return valid results before running your .NET Aspire application.
167+
168+
> [!TIP]
169+
> If you encounter issues with Podman in WSL environments, see [Container runtime 'podman' could not be found in WSL](../troubleshooting/podman-wsl-not-found.md) for specific troubleshooting guidance.
170+
136171
## .NET Aspire dashboard
137172

138173
.NET Aspire templates that expose the [app host](app-host-overview.md) project also include a useful developer [dashboard](dashboard/overview.md) that's used to monitor and inspect various aspects of your app, such as logs, traces, and environment configurations. This dashboard is designed to improve the local development experience and provides an overview of the overall state and structure of your app.

‎docs/get-started/migrate-from-docker-compose.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -367,6 +367,7 @@ When migrating from Docker Compose to .NET Aspire, you might encounter some comm
367367

368368
- [Docker Compose FAQ](https://docs.docker.com/compose/faq/)
369369
- [Container runtime unhealthy](../troubleshooting/container-runtime-unhealthy.md)
370+
- [Container runtime 'podman' could not be found in WSL](../troubleshooting/podman-wsl-not-found.md)
370371
- [.NET Aspire dashboard overview](../fundamentals/dashboard/overview.md)
371372

372373
## Next steps

‎docs/toc.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -498,6 +498,9 @@ items:
498498
href: troubleshooting/name-is-already-in-use.md
499499
- name: Container runtime appears to be unhealthy
500500
href: troubleshooting/container-runtime-unhealthy.md
501+
- name: Container runtime 'podman' could not be found in WSL
502+
displayName: podman,wsl,container runtime,linux
503+
href: troubleshooting/podman-wsl-not-found.md
501504
- name: The connection string is missing
502505
href: troubleshooting/connection-string-missing.md
503506
- name: Ask questions on Discord

‎docs/troubleshooting/podman-wsl-not-found.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
title: Container runtime 'podman' could not be found in WSL
3+
description: Learn how to troubleshoot the error "Container runtime 'podman' could not be found" when using Podman in Windows Subsystem for Linux (WSL).
4+
ms.date: 08/04/2025
5+
---
6+
7+
# Container runtime 'podman' could not be found in WSL
8+
9+
.NET Aspire requires a container runtime to be available in the system PATH. This article describes how to resolve issues when Podman isn't found in Windows Subsystem for Linux (WSL) environments.
10+
11+
## Symptoms
12+
13+
When starting your .NET Aspire application, you see an error message similar to:
14+
15+
```Output
16+
Container runtime 'podman' could not be found. The error from the container runtime check was: exec: "podman": executable file not found in $PATH
17+
```
18+
19+
This occurs even though running `podman images` or other Podman commands work successfully in your WSL terminal.
20+
21+
## Cause
22+
23+
This issue occurs in WSL environments when:
24+
25+
- Podman is installed in a separate WSL distribution than where your .NET Aspire application is running.
26+
- You're using shell aliases instead of having the actual Podman executable in your PATH.
27+
- The Podman executable isn't available in the system PATH that .NET Aspire searches.
28+
29+
.NET Aspire resolves container runtimes by searching for the executable in the system PATH. Shell aliases (like those defined in `~/.bash_aliases`) aren't recognized during this process.
30+
31+
## Solution
32+
33+
Choose one of the following solutions:
34+
35+
### Install Podman in the current WSL distribution
36+
37+
Install Podman directly in the WSL distribution where you're running your .NET Aspire application:
38+
39+
```bash
40+
# For Ubuntu/Debian-based distributions
41+
sudo apt update
42+
sudo apt install -y podman
43+
```
44+
45+
For other distributions, see [Install Podman on Linux](https://podman.io/docs/installation#installing-on-linux).
46+
47+
### Create a symbolic link
48+
49+
If you have Podman installed elsewhere, create a symbolic link:
50+
51+
```bash
52+
# Find where Podman is installed
53+
which podman-remote-static-linux_amd64
54+
55+
# Create a symbolic link in a directory that's in your PATH
56+
sudo ln -s /path/to/podman-remote-static-linux_amd64 /usr/local/bin/podman
57+
```
58+
59+
### Add Podman directory to PATH
60+
61+
Add the directory containing the Podman executable to your PATH:
62+
63+
```bash
64+
# Add to your shell profile
65+
echo 'export PATH="/path/to/podman/directory:$PATH"' >> ~/.bashrc
66+
source ~/.bashrc
67+
```
68+
69+
## Verify the solution
70+
71+
Confirm that Podman is correctly configured:
72+
73+
```bash
74+
# Check that Podman is in your PATH
75+
which podman
76+
77+
# Verify Podman is working
78+
podman --version
79+
80+
# Test that Podman can list containers
81+
podman ps
82+
```
83+
84+
All commands should succeed before running your .NET Aspire application.
85+
86+
## See also
87+
88+
- [Container runtime setup](../fundamentals/setup-tooling.md#container-runtime)
89+
- [Container runtime appears to be unhealthy](container-runtime-unhealthy.md)

0 commit comments

Comments
 (0)