Python feature to installJupyterLab fails on Python3.12 based environments with error: externally-managed-environment

[prabhakk-mw]

Codespaces /DevContainers using Python3.12 as the default interpreter lead to failed builds.

The following devcontainer.json configuration can be used to reproduce the issue.

{
  "name": "JupyterLab on Python3.12",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/python:1": {
      "version": "os-provided",
      "installJupyterlab": true
    }
  },
  "containerUser": "vscode"
}

Listed below are the errors displayed in the creation log:

<snip>
#15 80.18   These apps are now globally available
#15 80.18     - pylint
#15 80.18     - pylint-config
#15 80.18     - pyreverse
#15 80.18     - symilar
#15 80.21 Updating /etc/bash.bashrc and /etc/zsh/zshrc...
#15 80.21 Updating /etc/bash.bashrc and /etc/zsh/zshrc...2025-07-01 04:36:41.181Z: 
#15 80.22 Updating /etc/bash.bashrc and /etc/zsh/zshrc...
2025-07-01 04:36:41.314Z: #15 80.50 error: externally-managed-environment
#15 80.50 
#15 80.50 × This environment is externally managed
2025-07-01 04:36:41.315Z: #15 80.50 ╰─> To install Python packages system-wide, try apt install
#15 80.50     python3-xyz, where xyz is the package you are trying to
#15 80.50     install.
#15 80.50     
#15 80.50     If you wish to install a non-Debian-packaged Python package,
#15 80.50     create a virtual environment using python3 -m venv path/to/venv.
#15 80.50     Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
#15 80.50     sure you have python3-full installed.
#15 80.50     
#15 80.50     If you wish to install a non-Debian packaged Python application,
#15 80.50     it may be easiest to use pipx install xyz, which will manage a
#15 80.50     virtual environment for you. Make sure you have pipx installed.
#15 80.50     
#15 80.50     See /usr/share/doc/python3.12/README.venv for more information.
#15 80.50 
#15 80.50 note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
#15 80.50 hint: See PEP 668 for the detailed specification.
2025-07-01 04:36:41.504Z: #15 80.54 ERROR: Feature "Python" (ghcr.io/devcontainers/features/python) failed to install! Look at the documentation at ********/devcontainers/features/tree/main/src/python for help troubleshooting this error.
2025-07-01 04:36:43.410Z: #15 ERROR: process "/bin/sh -c cp -ar /tmp/build-features-src/python_0 /tmp/dev-container-features  && chmod -R 0755 /tmp/dev-container-features/python_0  && cd /tmp/dev-container-features/python_0  && chmod +x ./devcontainer-features-install.sh  && ./devcontainer-features-install.sh  && rm -rf /tmp/dev-container-features/python_0" did not complete successfully: exit code: 1
2025-07-01 04:36:43.432Z: ------
 > [dev_containers_target_stage 5/5] RUN --mount=type=bind,from=dev_containers_feature_content_source,source=python_0,target=/tmp/build-features-src/python_0     cp -ar /tmp/build-features-src/python_0 /tmp/dev-container-features  && chmod -R 0755 /tmp/dev-container-features/python_0  && cd /tmp/dev-container-features/python_0  && chmod +x ./devcontainer-features-install.sh  && ./devcontainer-features-install.sh  && rm -rf /tmp/dev-container-features/python_0:
80.50     
80.50     If you wish to install a non-Debian packaged Python application,
80.50     it may be easiest to use pipx install xyz, which will manage a
80.50     virtual environment for you. Make sure you have pipx installed.
80.50     
80.50     See /usr/share/doc/python3.12/README.venv for more information.
80.50 
80.50 note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
80.50 hint: See PEP 668 for the detailed specification.
80.54 ERROR: Feature "Python" (ghcr.io/devcontainers/features/python) failed to install! Look at the documentation at ********/devcontainers/features/tree/main/src/python for help troubleshooting this error.
------
2025-07-01 04:36:43.434Z: Dockerfile.extended:27
--------------------
  26 |     ENV PATH="/usr/local/python/current/bin:/usr/local/py-utils/bin:/usr/local/jupyter:${PATH}"
  27 | >>> RUN --mount=type=bind,from=dev_containers_feature_content_source,source=python_0,target=/tmp/build-features-src/python_0 \
  28 | >>>     cp -ar /tmp/build-features-src/python_0 /tmp/dev-container-features \
  29 | >>>  && chmod -R 0755 /tmp/dev-container-features/python_0 \
  30 | >>>  && cd /tmp/dev-container-features/python_0 \
2025-07-01 04:36:43.435Z:   31 | >>>  && chmod +x ./devcontainer-features-install.sh \
  32 | >>>  && ./devcontainer-features-install.sh \
  33 | >>>  && rm -rf /tmp/dev-container-features/python_0
  34 |     
--------------------
ERROR: failed to solve: process "/bin/sh -c cp -ar /tmp/build-features-src/python_0 /tmp/dev-container-features  && chmod -R 0755 /tmp/dev-container-features/python_0  && cd /tmp/dev-container-features/python_0  && chmod +x ./devcontainer-features-install.sh  && ./devcontainer-features-install.sh  && rm -rf /tmp/dev-container-features/python_0" did not complete successfully: exit code: 1
2025-07-01 04:36:43.441Z: Stop: Run: docker buildx build --load --build-context dev_containers_feature_content_source=/tmp/devcontainercli-root/container-features/0.76.0-1751344516956 --build-arg _DEV_CONTAINERS_BASE_IMAGE=mcr.microsoft.com/devcontainers/base:ubuntu --build-arg _DEV_CONTAINERS_IMAGE_USER=root --build-arg _DEV_CONTAINERS_FEATURE_CONTENT_SOURCE=dev_container_feature_content_temp --target dev_containers_target_stage -f /tmp/devcontainercli-root/container-features/0.76.0-1751344516956/Dockerfile.extended -t vsc-matlab-codespaces-498622a529a38d0f8e680502a79ed27183f90abd78f00fdca6a506d844464a3e-features /var/lib/docker/codespacemount/.persistedshare/empty-folder
2025-07-01 04:36:43.443Z: Error: Command failed: docker buildx build --load --build-context dev_containers_feature_content_source=/tmp/devcontainercli-root/container-features/0.76.0-1751344516956 --build-arg _DEV_CONTAINERS_BASE_IMAGE=mcr.microsoft.com/devcontainers/base:ubuntu --build-arg _DEV_CONTAINERS_IMAGE_USER=root --build-arg _DEV_CONTAINERS_FEATURE_CONTENT_SOURCE=dev_container_feature_content_temp --target dev_containers_target_stage -f /tmp/devcontainercli-root/container-features/0.76.0-1751344516956/Dockerfile.extended -t vsc-matlab-codespaces-498622a529a38d0f8e680502a79ed27183f90abd78f00fdca6a506d844464a3e-features /var/lib/docker/codespacemount/.persistedshare/empty-folder
2025-07-01 04:36:43.443Z: {"outcome":"error","message":"Command failed: docker buildx build --load --build-context dev_containers_feature_content_source=/tmp/devcontainercli-root/container-features/0.76.0-1751344516956 --build-arg _DEV_CONTAINERS_BASE_IMAGE=mcr.microsoft.com/devcontainers/base:ubuntu --build-arg _DEV_CONTAINERS_IMAGE_USER=root --build-arg _DEV_CONTAINERS_FEATURE_CONTENT_SOURCE=dev_container_feature_content_temp --target dev_containers_target_stage -f /tmp/devcontainercli-root/container-features/0.76.0-1751344516956/Dockerfile.extended -t vsc-matlab-codespaces-498622a529a38d0f8e680502a79ed27183f90abd78f00fdca6a506d844464a3e-features /var/lib/docker/codespacemount/.persistedshare/empty-folder","description":"An error occurred setting up the container."}
2025-07-01 04:36:43.443Z:     at D6 (/.codespaces/agent/bin/node_modules/@devcontainers/cli/dist/spec-node/devContainersSpecCLI.js:467:1253)
2025-07-01 04:36:43.444Z:     at Ix (/.codespaces/agent/bin/node_modules/@devcontainers/cli/dist/spec-node/devContainersSpecCLI.js:467:997)
2025-07-01 04:36:43.457Z:     at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
2025-07-01 04:36:43.457Z: devcontainer process exited with exit code 1
2025-07-01 04:36:43.458Z:     at async Y6 (/.codespaces/agent/bin/node_modules/@devcontainers/cli/dist/spec-node/devContainersSpecCLI.js:484:3842)
2025-07-01 04:36:43.459Z:     at async BC (/.codespaces/agent/bin/node_modules/@devcontainers/cli/dist/spec-node/devContainersSpecCLI.js:484:4957)
2025-07-01 04:36:43.460Z:     at async p7 (/.codespaces/agent/bin/node_modules/@devcontainers/cli/dist/spec-node/devContainersSpecCLI.js:665:202)
2025-07-01 04:36:43.461Z:     at async d7 (/.codespaces/agent/bin/node_modules/@devcontainers/cli/dist/spec-node/devContainersSpecCLI.js:664:14804)
2025-07-01 04:36:43.462Z:     at async /.codespaces/agent/bin/node_modules/@devcontainers/cli/dist/spec-node/devContainersSpecCLI.js:484:1188

====================================== ERROR ====================================
2025-07-01 04:36:43.472Z: Failed to create container.
=================================================================================
2025-07-01 04:36:43.472Z: Error: Command failed: docker buildx build --load --build-context dev_containers_feature_content_source=/tmp/devcontainercli-root/container-features/0.76.0-1751344516956 --build-arg _DEV_CONTAINERS_BASE_IMAGE=mcr.microsoft.com/devcontainers/base:ubuntu --build-arg _DEV_CONTAINERS_IMAGE_USER=root --build-arg _DEV_CONTAINERS_FEATURE_CONTENT_SOURCE=dev_container_feature_content_temp --target dev_containers_target_stage -f /tmp/devcontainercli-root/container-features/0.76.0-1751344516956/Dockerfile.extended -t vsc-matlab-codespaces-498622a529a38d0f8e680502a79ed27183f90abd78f00fdca6a506d844464a3e-features /var/lib/docker/codespacemount/.persistedshare/empty-folder
2025-07-01 04:36:43.473Z: Error code: 1302 (UnifiedContainersErrorFatalCreatingContainer)

====================================== ERROR ====================================
2025-07-01 04:36:43.480Z: Container creation failed.
=================================================================================
2025-07-01 04:36:43.489Z: 

===================================== WARNING ===================================
2025-07-01 04:36:43.490Z: Creating recovery container.
=================================================================================
<snip>

See Python Doc for Externally managed Environments for more information about the error.

User Expectation:
Using the python feature does not fail when installJupyterLab is true and codespaces using the feature can be opened in the JupyterLab editor.

[Kaniska244]

Hello @prabhakk-mw ,

Thank you for reporting this issue. Looks like with system provided python package its not possible to run pip install in Ubuntu 23.04 onwards & also in debian 12 due to implementation of PEP-668 as in the feature pip install is used to install jupyterlab python tool. Ref
Alternatively you could use specific python or latest in your devcontainer python feature configuration instead of using os-provided. Meanwhile at devcontainers side we will look at the possibility of a fix for this.
Kindly let me know in case of any further concern with this.

[Kaniska244]

Hello @prabhakk-mw ,

Closing this issue as we are not planning any fix for this as its mainly due to PEP-668 restriction and there are multiple different ways to work this around including specifying the Python version in the feature or using a package manager such as Conda to install Jupyterlab. Kindly let me know in case of any further concern on this.