> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sphinx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to Different Backends

> Use Sphinx with Databricks, Google Colab, Azure ML, AWS SageMaker, JupyterHub, and other notebook environments

## Overview

Sphinx works with any Jupyter kernel that VS Code can connect to. This means you can use Sphinx with cloud notebooks, remote servers, and enterprise data platforms—not just local Python environments.

<Note>
  Sphinx requires the [Microsoft Jupyter extension](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter) (`ms-toolsai.jupyter`), which is automatically installed as a dependency when you install Sphinx.
</Note>

## How It Works

Sphinx uses VS Code's standardized notebook and kernel APIs provided by the Jupyter extension. When you connect VS Code to a remote kernel or cloud notebook environment, Sphinx automatically works with that connection—no additional configuration required.

```mermaid actions={false} theme={null}
flowchart TD
    SphinxExt[Sphinx Extension]
    JupyterExt[Microsoft Jupyter Extension]
    Local[Local Python]
    Remote[Remote Jupyter]
    Cloud[Cloud Notebooks]
    
    SphinxExt -->|VS Code Jupyter API| JupyterExt
    JupyterExt --> Local
    JupyterExt --> Remote
    JupyterExt --> Cloud
```

## Supported Backends

### Databricks

Connect Sphinx to Databricks notebooks and clusters for enterprise data workflows.

<Card title="Databricks Extension" icon="database" href="https://marketplace.visualstudio.com/items?itemName=databricks.databricks">
  Official Databricks extension for VS Code with notebook and cluster support.
</Card>

**Installation:**

1. Install the [Databricks extension](https://marketplace.visualstudio.com/items?itemName=databricks.databricks) from the VS Code Marketplace
2. Configure your Databricks workspace connection
3. Open or create a notebook in your Databricks workspace
4. Select a Databricks cluster as your kernel
5. Use Sphinx with `Cmd+T` / `Ctrl+T`

**Resources:**

* [Databricks VS Code Extension Documentation](https://docs.databricks.com/en/dev-tools/vscode-ext/index.html)
* [Connect to Databricks Clusters](https://docs.databricks.com/en/dev-tools/vscode-ext/clusters.html)

<Tip>
  For Databricks data connections, you can also use Sphinx's [integration credentials](/configuration/integrations) to securely access Databricks data from any kernel.
</Tip>

***

### Google Colab

Run Sphinx with Google Colab notebooks for free GPU/TPU access.

<Card title="Colab Extension" icon="google" href="https://marketplace.visualstudio.com/items?itemName=Google.colab">
  Connect VS Code to Google Colab runtimes.
</Card>

**Installation:**

1. Install the [Google Colab extension](https://marketplace.visualstudio.com/items?itemName=Google.colab)
2. Sign in with your Google account
3. Connect to a Colab runtime (GPU/TPU available)
4. Open your `.ipynb` file
5. Use Sphinx

**Resources:**

* [Colab on VS Code announcement](https://developers.googleblog.com/google-colab-is-coming-to-vs-code/)

***

### BigQuery Notebooks (Google Cloud)

Use Sphinx with BigQuery notebooks for large-scale data analysis.

<Card title="Google Cloud Code" icon="cloud" href="https://marketplace.visualstudio.com/items?itemName=GoogleCloudTools.cloudcode">
  Google Cloud extension with BigQuery notebook support.
</Card>

**Installation:**

1. Install [Google Cloud Code](https://marketplace.visualstudio.com/items?itemName=GoogleCloudTools.cloudcode)
2. Authenticate with your Google Cloud account
3. Install the BigFrames library:
   ```bash theme={null}
   pip install bigframes
   ```
4. Use Sphinx to query and analyze data

**Resources:**

* [BigQuery Notebooks in VS Code](https://cloud.google.com/bigquery/docs/notebooks-introduction)
* [Google Cloud Code Documentation](https://cloud.google.com/code/docs/vscode)

***

### Azure Machine Learning

Connect to Azure ML compute instances and managed notebooks.

<Card title="Azure Machine Learning" icon="microsoft" href="https://marketplace.visualstudio.com/items?itemName=ms-toolsai.vscode-ai">
  Official Azure ML extension for VS Code.
</Card>

**Installation:**

1. Install the [Azure Machine Learning extension](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.vscode-ai)
2. Sign in to your Azure account
3. Connect to your Azure ML workspace
4. Create or attach to a compute instance
5. Open notebooks and use Sphinx

**Resources:**

* [Azure ML VS Code Extension](https://learn.microsoft.com/en-us/azure/machine-learning/how-to-setup-vs-code)
* [Manage Compute Instances](https://learn.microsoft.com/en-us/azure/machine-learning/how-to-create-compute-instance)

***

### Amazon SageMaker

Use Sphinx with SageMaker notebook instances and Studio.

<Card title="AWS Toolkit" icon="aws" href="https://docs.aws.amazon.com/sagemaker/latest/dg/remote-access.html">
  AWS Toolkit with SageMaker integration.
</Card>

**Resources:**

* [AWS Toolkit for VS Code](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/welcome.html)
* [SageMaker in VS Code](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-lab-use-external-ide.html)

***

### JupyterHub / Remote Jupyter Servers

Connect to any JupyterHub deployment or remote Jupyter server.

<Card title="Jupyter Extension" icon="jupyter" href="https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter">
  Built-in support for remote Jupyter connections.
</Card>

**Connect to a Remote Server:**

1. Open VS Code Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
2. Run **"Jupyter: Specify Jupyter Server for Connections"**
3. Select **"Existing"** and enter your server URL
4. Authenticate if required (token or password)
5. Your remote kernels appear in the kernel picker

**Connect to JupyterHub:**

1. Get your JupyterHub server URL (e.g., `https://hub.example.com`)
2. Use the same connection flow as remote servers
3. Authenticate with your JupyterHub credentials
4. Access your hub-managed kernels

**Resources:**

* [Connect to Remote Jupyter Servers](https://code.visualstudio.com/docs/datascience/jupyter-notebooks#_connect-to-a-remote-jupyter-server)

***

### Conda Environments

Use Sphinx with different Conda environments on your local machine.

**Setup:**

1. Ensure the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) is installed
2. Create or activate a Conda environment with Jupyter:
   ```bash theme={null}
   conda create -n myenv python=3.11 ipykernel
   conda activate myenv
   python -m ipykernel install --user --name myenv
   ```
3. Open a notebook in VS Code
4. Select your Conda environment from the kernel picker
5. Use Sphinx with your Conda kernel

***

## Open VSX Registry

If you're using an open-source VS Code distribution or fork (Cursor, Windsurf, etc.) that uses the [Open VSX Registry](https://open-vsx.org/) instead of the Microsoft Marketplace, you can find compatible extensions there:

| Extension | Open VSX Link                                                                                  |
| --------- | ---------------------------------------------------------------------------------------------- |
| Jupyter   | [open-vsx.org/extension/ms-toolsai/jupyter](https://open-vsx.org/extension/ms-toolsai/jupyter) |
| Python    | [open-vsx.org/extension/ms-python/python](https://open-vsx.org/extension/ms-python/python)     |

<Warning>
  Some proprietary extensions (Databricks, Azure ML, AWS Toolkit) may not be available on Open VSX. Check each extension's licensing and availability.
</Warning>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sphinx doesn't see my remote kernel">
    1. Ensure the kernel is running and connected in VS Code
    2. Try executing a cell manually first to activate the kernel
    3. Check that the Jupyter extension shows the kernel in the status bar
    4. Restart VS Code if the kernel was recently connected
  </Accordion>

  <Accordion title="Kernel disconnects frequently">
    Remote kernels may disconnect due to network issues or idle timeouts. Try:

    * Increasing your server's idle timeout settings
    * Using a more stable network connection
    * Checking your cloud provider's kernel persistence settings
  </Accordion>

  <Accordion title="Performance is slow with remote kernels">
    Sphinx streams data between your machine and the remote kernel. For better performance:

    * Use kernels geographically close to you
    * Consider using the remote kernel for heavy computation only
    * Keep datasets on the remote machine when possible
  </Accordion>

  <Accordion title="Extension not compatible with my VS Code fork">
    Sphinx requires the Microsoft Jupyter extension API. If you're using an alternative VS Code distribution:

    1. Ensure `ms-toolsai.jupyter` is installed and working
    2. Check that the Jupyter extension version is 2024.1.0 or later
    3. Some forks may have compatibility issues—try the official VS Code if problems persist
  </Accordion>
</AccordionGroup>

***

## Best Practices

<Steps>
  <Step title="Verify kernel connection first">
    Before using Sphinx, run a simple cell (like `print("hello")`) to ensure your kernel is connected and responsive.
  </Step>

  <Step title="Keep notebooks saved">
    Remote connections can be unstable. Enable VS Code's autosave and Sphinx's autosave feature to prevent data loss.
  </Step>

  <Step title="Use appropriate compute">
    Match your compute resources to your task. Use GPU kernels for deep learning, high-memory instances for large datasets.
  </Step>

  <Step title="Manage credentials securely">
    Use Sphinx's [Secrets](/configuration/secrets) and [Integrations](/configuration/integrations) features to manage API keys and database credentials instead of hardcoding them in notebooks.
  </Step>
</Steps>