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

# encryptd FAQ: Passphrases, Platforms, and Configuration

> Answers to common questions about encryptd: passphrase security, committing encrypted files, multiple environments, runtime loading, and more.

Below you will find answers to the questions most commonly asked about encryptd. If your question is not covered here, check the [Troubleshooting](/help/troubleshooting) page or open an issue in the project repository.

<AccordionGroup>
  <Accordion title="Is it safe to commit `.env.enc` to version control?">
    Yes. The `.env.enc` file is encrypted with AES-256-GCM, a widely trusted authenticated encryption algorithm. Without the correct passphrase, the ciphertext is computationally unreadable.

    Follow these rules to keep your secrets safe:

    * **Commit** `.env.enc` — this is the intended workflow.
    * **Never commit** the original `.env` file or your passphrase.
    * Add `.env` to your `.gitignore` to prevent accidental commits.

    ```gitignore .gitignore theme={null}
    .env
    .env.*
    !.env.enc
    !.env.*.enc
    ```

    <Warning>
      The security guarantee only holds as long as your passphrase remains secret. Rotate the passphrase immediately if you suspect it has been exposed.
    </Warning>
  </Accordion>

  <Accordion title="What happens if the same `.env` is encrypted twice?">
    The resulting ciphertext will be different each time, even if the input file and passphrase are identical. encryptd generates a fresh random salt and nonce (IV) on every encryption run, so no two `.env.enc` files will ever be the same.

    Both files will decrypt to the same plaintext content when the correct passphrase is provided. This is expected and correct behaviour.
  </Accordion>

  <Accordion title="Can I use multiple encrypted files for different environments?">
    Yes. Specify custom input and output file paths when encrypting:

    ```bash Encrypt environment-specific files theme={null}
    npx secure-env encrypt .env.staging .env.staging.enc
    npx secure-env encrypt .env.prod    .env.prod.enc
    ```

    Then load the appropriate file at runtime using the `path` option:

    ```ts Load by environment theme={null}
    import { config } from '@vernonthedev/encryptd';

    config({ path: '.env.staging.enc' });
    ```

    <Tip>
      Use a `NODE_ENV` check or a dedicated environment variable to select the correct `.enc` file automatically in your application bootstrap code.
    </Tip>
  </Accordion>

  <Accordion title="Does `config()` overwrite existing `process.env` variables?">
    No — by default, `config()` will not overwrite a key that already exists in `process.env`. This preserves values injected by your shell, Docker, or deployment environment, which typically take precedence over file-based configuration.

    If you need the values in the encrypted file to take precedence, set the `override` option to `true`:

    ```ts config() with override theme={null}
    import { config } from '@vernonthedev/encryptd';

    config({ override: true });
    ```
  </Accordion>

  <Accordion title="Do I need Rust installed to use encryptd?">
    No. encryptd ships prebuilt native binaries for all supported platforms. When you run `npm install`, the correct binary for your operating system and architecture is downloaded automatically — no Rust toolchain required.
  </Accordion>

  <Accordion title="What Node.js version is required?">
    Node.js **18 or higher** is recommended. Older versions may work but are not officially tested or supported.

    <Note>
      Always use an actively maintained Node.js LTS release in production. Check the [Node.js release schedule](https://nodejs.org/en/about/previous-releases) for current LTS versions.
    </Note>
  </Accordion>

  <Accordion title="What if my platform isn't in the supported list?">
    encryptd currently provides prebuilt binaries for the following platforms:

    | OS      | Architecture          | libc          |
    | ------- | --------------------- | ------------- |
    | macOS   | ARM64 (Apple Silicon) | —             |
    | macOS   | x64 (Intel)           | —             |
    | Linux   | x64                   | GNU (`glibc`) |
    | Windows | x64                   | —             |

    If your platform is not listed — for example, Alpine Linux (musl), Linux ARM64, or 32-bit systems — encryptd is not currently supported there. Running inside a Docker container based on a `glibc` Linux distribution (such as Debian or Ubuntu) is the recommended workaround for most CI and server environments.

    Watch the project repository for updates if support for your platform is important to you.
  </Accordion>

  <Accordion title="How do I rotate the passphrase?">
    Rotating the passphrase is a two-step process: decrypt with the old passphrase, then re-encrypt with the new one.

    ```bash Rotate passphrase theme={null}
    # Step 1: Decrypt using the old passphrase
    ENV_PASSPHRASE="old-passphrase" npx secure-env decrypt .env.enc .env

    # Step 2: Re-encrypt using the new passphrase
    ENV_PASSPHRASE="new-passphrase" npx secure-env encrypt .env .env.enc
    ```

    After rotation, update `ENV_PASSPHRASE` in every environment that uses the file — local developer machines, deployment secrets, and server environment variables — before deploying the new `.env.enc`.

    <Warning>
      Delete or securely shred the intermediate plaintext `.env` file after re-encryption to avoid leaving secrets on disk.
    </Warning>
  </Accordion>
</AccordionGroup>