diff --git a/doc/changelog.d/1574.documentation.md b/doc/changelog.d/1574.documentation.md
new file mode 100644
index 0000000000..2eacc88e16
--- /dev/null
+++ b/doc/changelog.d/1574.documentation.md
@@ -0,0 +1 @@
+Add documentation on how to debug embedded app in linux using vscode
diff --git a/doc/source/getting_started/running_mechanical.rst b/doc/source/getting_started/running_mechanical.rst
index ebc7332128..188b361137 100644
--- a/doc/source/getting_started/running_mechanical.rst
+++ b/doc/source/getting_started/running_mechanical.rst
@@ -121,4 +121,4 @@ For more on embedding, see the :ref:`Embedding mode user guide <ref_embedding_us
 
 .. seealso::
 
-   :doc:`troubleshooting` — executable not found, licensing, VPN, and debug tips.
+   :doc:`troubleshooting` — executable not found, licensing, VPN, and debug tips.
\ No newline at end of file
diff --git a/doc/source/getting_started/troubleshooting.rst b/doc/source/getting_started/troubleshooting.rst
index 7be097a5b2..2a60b9bc50 100644
--- a/doc/source/getting_started/troubleshooting.rst
+++ b/doc/source/getting_started/troubleshooting.rst
@@ -46,6 +46,52 @@ If this command doesn't launch Mechanical, common causes include:
 - Running behind a VPN
 - Missing dependencies
 
+.. _debug-embedding-vscode-linux:
+
+Debug with Visual Studio Code on Linux
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On Linux, the Python debugger must see the same environment that ``mechanical-env`` sets when
+On Linux, the Python debugger must see the same environment that the ``mechanical-env`` variable sets when
+you run ``mechanical-env python``. You can capture that environment once, store it in a file, and
+point Visual Studio Code at it.
+
+#. Install the `Python extension`_ for Visual Studio Code (provides the Debuggy debugger).
+
+#. From your project root, write the prepared environment to ``.vscode/.env``. Use the same
+   ``-r`` or ``-p`` options you use for normal runs:
+
+   .. code:: shell
+
+      $ mechanical-env -r 261 env > .vscode/.env
+
+#. Create ``.vscode/launch.json`` with a launch configuration that loads that file:
+
+   .. code-block:: json
+
+      {
+          "version": "0.2.0",
+          "configurations": [
+              {
+                  "name": "Python Debugger: Current File",
+                  "type": "debugpy",
+                  "request": "launch",
+                  "program": "${file}",
+                  "console": "integratedTerminal",
+                  "envFile": "${workspaceFolder}/.vscode/.env"
+              }
+          ]
+      }
+
+#. Start **Run and Debug**, choose **Python Debugger: Current File**, and run your script.
+
+.. note::
+
+   Regenerate ``.vscode/.env`` if you change the Ansys version, installation path, or ``mechanical-env``
+   options. Consider adding ``.env`` to ``.gitignore`` if the file should not be shared.
+
+.. _`Python extension`: https://marketplace.visualstudio.com/items?itemName=ms-python.python
+
 
 Licensing issues
 -----------------
diff --git a/doc/source/user_guide/cli/mechanical-env.rst b/doc/source/user_guide/cli/mechanical-env.rst
index c4845453a2..638aa803f2 100644
--- a/doc/source/user_guide/cli/mechanical-env.rst
+++ b/doc/source/user_guide/cli/mechanical-env.rst
@@ -50,3 +50,10 @@ Run a Python script using a specific version:
 .. code-block:: bash
 
    mechanical-env -r 261 python my_script.py
+
+Debugging with Visual Studio Code
+---------------------------------
+
+To debug embedded PyMechanical scripts in VS Code on Linux, export the environment that
+``mechanical-env`` would set and attach the debugger to it. See
+:ref:`debug-embedding-vscode-linux` in :doc:`/getting_started/running_mechanical`.