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

# Configure your API key

> Avoid hardcoding secrets

## Prerequisites

[Create an API key](/api-reference/preparation/api-key) first, in the region you will call. The environment variable stores only the key; your code must also use the Base URL of the same region. See [Regions and endpoints](/developer-guides/getting-started/regions).

## Steps

<Tabs>
  <Tab title="Linux">
    ### Permanent environment variable

    Set a permanent environment variable for the current user:

    <Steps>
      <Step title="Add the environment variable">
        Add the variable to `~/.bashrc`:

        ```bash
        # Replace YOUR_DASHSCOPE_API_KEY with your API key.
        echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bashrc
        ```

        <Accordion title="Edit manually">
          Open `~/.bashrc`:

          ```bash
          nano ~/.bashrc
          ```

          Add the following content to the file:

          ```bash
          # Replace YOUR_DASHSCOPE_API_KEY with your API key.
          export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
          ```

          In the nano editor, press Ctrl+X and then Y. Press Enter to save and close the file.
        </Accordion>
      </Step>

      <Step title="Apply the changes">
        Apply changes:

        ```bash
        source ~/.bashrc
        ```
      </Step>

      <Step title="Verify">
        Verify in a new session:

        ```bash
        echo $DASHSCOPE_API_KEY
        ```
      </Step>
    </Steps>

    ### Temporary environment variable

    Set a temporary variable (current session only):

    <Steps>
      <Step title="Set the variable">
        ```bash
        # Replace YOUR_DASHSCOPE_API_KEY with your API key.
        export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
        ```
      </Step>

      <Step title="Verify">
        ```bash
        echo $DASHSCOPE_API_KEY
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="macOS">
    ### Permanent environment variable

    Set a permanent environment variable for the current user:

    <Steps>
      <Step title="Check your default shell type">
        ```bash
        echo $SHELL
        ```
      </Step>

      <Step title="Add the environment variable">
        <Tabs>
          <Tab title="Zsh">
            Add the variable to `~/.zshrc`:

            ```zsh
            # Replace YOUR_DASHSCOPE_API_KEY with your API key.
            echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.zshrc
            ```

            <Accordion title="Edit manually">
              Open `~/.zshrc`:

              ```zsh
              nano ~/.zshrc
              ```

              Add the following content to the file:

              ```bash
              # Replace YOUR_DASHSCOPE_API_KEY with your API key.
              export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
              ```

              In the nano editor, press Ctrl+X and then Y. Press Enter to save and close the file.
            </Accordion>
          </Tab>

          <Tab title="Bash">
            Add the variable to `~/.bash_profile`:

            ```bash
            # Replace YOUR_DASHSCOPE_API_KEY with your API key.
            echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bash_profile
            ```

            <Accordion title="Edit manually">
              Open `~/.bash_profile`:

              ```bash
              nano ~/.bash_profile
              ```

              Add the following content to the file:

              ```bash
              # Replace YOUR_DASHSCOPE_API_KEY with your API key.
              export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
              ```

              In the nano editor, press Ctrl+X and then Y. Press Enter to save and close the file.
            </Accordion>
          </Tab>
        </Tabs>
      </Step>

      <Step title="Apply the changes">
        <Tabs>
          <Tab title="Zsh">
            ```zsh
            source ~/.zshrc
            ```
          </Tab>

          <Tab title="Bash">
            ```bash
            source ~/.bash_profile
            ```
          </Tab>
        </Tabs>
      </Step>

      <Step title="Verify">
        Verify in a new session:

        ```zsh
        echo $DASHSCOPE_API_KEY
        ```
      </Step>
    </Steps>

    ### Temporary environment variable

    Set a temporary variable (current session only):

    <Steps>
      <Step title="Set the variable">
        ```bash
        # Replace YOUR_DASHSCOPE_API_KEY with your API key.
        export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
        ```
      </Step>

      <Step title="Verify">
        ```bash
        echo $DASHSCOPE_API_KEY
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windows">
    Set environment variables through System Properties, CMD, or PowerShell.

    <Tabs>
      <Tab title="System Properties">
        <Note>
          - Permanent environment variable (requires admin permissions)
          - Takes effect in new sessions only — restart terminals, IDEs, and apps
        </Note>

        <Steps>
          <Step title="Open System Properties">
            Press `Win+Q`, search for "**Edit the system environment variables**", and open **System Properties**.
          </Step>

          <Step title="Add the environment variable">
            Click **Environment Variables** > **System Variables** > **New**. Set name to `DASHSCOPE_API_KEY` and value to your API key.

            <img src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/0439247371/p894015.png" alt="System environment variable dialog" />
          </Step>

          <Step title="Confirm">
            Click **OK** on all three dialog boxes.
          </Step>

          <Step title="Verify">
            Verify in CMD or PowerShell:

            - CMD:

            ```powershell
            echo %DASHSCOPE_API_KEY%
            ```

            <img src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/9623589371/p912522.png" alt="CMD verification" />

            - Windows PowerShell:

            ```powershell
            echo $env:DASHSCOPE_API_KEY
            ```

            <img src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/9623589371/p912525.png" alt="PowerShell verification" />
          </Step>
        </Steps>
      </Tab>

      <Tab title="CMD">
        #### Permanent environment variable

        <Steps>
          <Step title="Set the variable">
            ```batch
            # Replace YOUR_DASHSCOPE_API_KEY with your API key.
            setx DASHSCOPE_API_KEY "YOUR_DASHSCOPE_API_KEY"
            ```
          </Step>

          <Step title="Open a new session">
            Open a new CMD session.
          </Step>

          <Step title="Verify">
            ```batch
            echo %DASHSCOPE_API_KEY%
            ```

            <img src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/9623589371/p912522.png" alt="CMD verification" />
          </Step>
        </Steps>

        #### Temporary environment variable

        <Steps>
          <Step title="Run the following command">
            ```batch
            # Replace YOUR_DASHSCOPE_API_KEY with your API key.
            set DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
            ```
          </Step>

          <Step title="Verify">
            ```batch
            echo %DASHSCOPE_API_KEY%
            ```

            <img src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/9623589371/p912522.png" alt="CMD verification" />
          </Step>
        </Steps>
      </Tab>

      <Tab title="PowerShell">
        #### Permanent environment variable

        <Steps>
          <Step title="Set the variable">
            ```powershell
            # Replace YOUR_DASHSCOPE_API_KEY with your API key.
            [Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "YOUR_DASHSCOPE_API_KEY", [EnvironmentVariableTarget]::User)
            ```
          </Step>

          <Step title="Open a new session">
            Open a new PowerShell session.
          </Step>

          <Step title="Verify">
            ```powershell
            echo $env:DASHSCOPE_API_KEY
            ```

            <img src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/9623589371/p912525.png" alt="PowerShell verification" />
          </Step>
        </Steps>

        #### Temporary environment variable

        <Steps>
          <Step title="Run the following command">
            ```powershell
            # Replace YOUR_DASHSCOPE_API_KEY with your API key.
            $env:DASHSCOPE_API_KEY = "YOUR_DASHSCOPE_API_KEY"
            ```
          </Step>

          <Step title="Verify">
            ```powershell
            echo $env:DASHSCOPE_API_KEY
            ```

            <img src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/9623589371/p912525.png" alt="PowerShell verification" />
          </Step>
        </Steps>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## FAQ

### echo works but code reports "no API key found"

Common causes:

- **Non-permanent variable**: Temporary variables work in the current session only. Set a permanent variable instead.

- **Need restart**: Restart IDE, terminal, or app. Service-managed apps may need service restart.

- **Service manager config**: For service-managed apps (systemd, supervisord), add the variable to the service config file.

- **Using sudo**: `sudo` doesn't inherit environment variables. Use `sudo -E python xx.py` (the `-E` flag passes variables) or run without `sudo` if permissions allow.

- **Base URL required**: Set QwenCloud's base URL for the region where the API key was created:

  - In code:

```python
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
dashscope.base_http_api_url = 'https://ap-southeast-1.maas.qwencloudapi.com/api/v1'
```

- As environment variable:

```bash
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
export DASHSCOPE_HTTP_BASE_URL='https://ap-southeast-1.maas.qwencloudapi.com/api/v1'
```