> This page location: /docs.md > /docs/tools-and-connectors.md > /docs/atlas/cli/current.md > /docs/atlas/cli/current/atlas-cli-tutorials.md > /docs/atlas/cli/current/atlas-cli-local-cloud.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  other tabs: interactive-default, interactive-custom, noninteractive
-->

# Create a Local Atlas Deployment

**Important:**

The `atlas deployments` commands are deprecated as of Atlas CLI version 1.52.0. Use `atlas local` commands instead. We updated this tutorial to use the `atlas local` command.

This tutorial shows you how to use the `atlas local` command to create a local Atlas deployment. In this tutorial, we will deploy a single-node replica set on your local computer. You can then manage your deployment, and use MongoDB Search and MongoDB Vector Search.

## Supported OS for Local Atlas Deployments

| Operating System | Operating System Version | Architecture | Minimum CPU Cores | Minimum Free RAM (GB) |
| --- | --- | --- | --- | --- |
| MacOS | Latest | x86-64, ARM | 2 | 2 |
| Red Hat Enterprise Linux / CentOS | 8, 9 | x86-64, ARM | 2 | 2 |
| Ubuntu | 22.04, 24.04 | x86-64, ARM | 2 | 2 |
| Debian | 11, 12 | x86-64, ARM | 2 | 2 |
| Amazon Linux | 2023 | x86-64, ARM | 2 | 2 |
| Windows | 10, 11 | x86 | 2 | 2 |

## Complete the Prerequisites

Before you begin, complete the following prerequisites:

**Important:**

For compatibility information on each product in the dependencies list, see the product's installation documentation.

1. Install the dependencies.

   Install the [Atlas CLI.](https://www.mongodb.com/docs/atlas/cli/current/install-atlas-cli.md#std-label-install-atlas-cli)

   If you use [Homebrew](https://brew.sh/#install), you can run the following command in your terminal:

   ```text
   brew install mongodb-atlas
   ```

   For installation instructions on other operating systems, see [Install or Update the Atlas CLI.](https://www.mongodb.com/docs/atlas/cli/current/install-atlas-cli.md#std-label-install-atlas-cli)

   Install [Docker.](https://www.docker.com/)

   Docker requires a network connection for pulling and caching MongoDB images.

   - For MacOS or Windows, install [Docker Desktop v4.31+.](https://docs.docker.com/desktop/release-notes/#4310)

   - For Linux, install [Docker Engine v27.0+.](https://docs.docker.com/engine/release-notes/27/)

   - For Linux RHEL, you can also use [Podman v5.0+.](https://podman.io)

   (Optional) Install [mongosh](https://www.mongodb.com/docs/mongodb-shell/install/) version 2.0 or later.

   ```sh
   brew install mongosh
   ```

   For installation instructions on other operating systems, see [Install mongosh.](https://www.mongodb.com/docs/mongodb-shell/install/)

   (Optional) Install [Compass](https://www.mongodb.com/docs/compass/current/install/) version 1.39.4 or later.

   ```sh
   brew install mongodb-compass
   ```

   For installation instructions on other operating systems, see [Download and Install Compass.](https://www.mongodb.com/docs/compass/current/install/)

   (Optional) Install [Visual Studio Code](https://code.visualstudio.com/download) and [MongoDB for VS Code Extension.](https://www.mongodb.com/docs/mongodb-vscode/install/)

   To learn more, see [Install MongoDB for VS Code Extension.](https://www.mongodb.com/docs/mongodb-vscode/install/)

2. Create an Atlas account.

## Create a Local Atlas Deployment

Use the `atlas local` command to create a local Atlas deployment.

You can run this command in the following ways:

- **Interactive Mode (Default)**: the command prompts you for the deployment settings and provides default values.

- **Interactive Mode (Custom)**: the command prompts you for the deployment settings and lets you provide custom values.

- **Non-Interactive Mode**: you run the command with the specified options. The command does not prompt you to provide further values. To learn all of the actions that `atlas local` supports, see `atlas-local`.

Click one of the following tabs to see the command for your preferred mode.

### Interactive (Default)

1. Run the `atlas local` command in interactive mode.

   ```sh
   atlas local setup
   ```

   To load MongoDB sample data during setup:

   Run the following command:

   ```sh
   atlas local setup --loadSampleData true
   ```

   To initialize the local Atlas deployment with your own data and indexes:

   Copy the following command:

   ```sh
   atlas local setup --initdb {folder}
   ```

   Replace the `{folder}` placeholder with the directory that contains the `.js` and `.sh` files to run inside the local container in alphanumeric order.

   Run the command.

2. Specify what to deploy.

   **Example:**

   Specify `local - Local Database` and press Enter.

   ```sh
   ? What would you like to deploy?  [Use arrows to move, type to filter, ? for more help]
   > local - Local Database
     atlas - Atlas Database
   ```

   **Output:**

   ```sh
   [Default Settings]
   Deployment Name   local50
   MongoDB Version   7.0
   Port              27017
   ```

3. Specify how to set up your local Atlas database.

   **Example:**

   Specify `default - With default settings` and press Enter.

   ```sh
   ? How do you want to setup your local MongoDB database?  [Use arrows to move, type to filter]
   > default - With default settings
     custom - With custom settings
     cancel - Cancel set up
   ```

   **Output:**

   ```sh
   Creating your deployment local50 [this might take several minutes]
   1/4: Downloading and completing configuration...
   2/4: Starting your local environment...
   3/4: Downloading MongoDB binaries to your local environment...
   4/4: Creating your deployment local50...
   Deployment created!
   Connection string: mongodb://localhost:27017/?directConnection=true
   ```

## Python Alternative: Create a Local Atlas Deployment

As an alternative to the Atlas CLI, you can use the `atlas-local-lib-py` Python library to programmatically create and manage local Atlas database deployments. This approach is useful for Python-based workflows, automated testing, and integration with Python applications.

### Prerequisites

Before you begin, ensure you have the following:

- Python 3.10 or later

- Docker Desktop or Docker Engine installed and running

### Install the Library

Install `atlas-local-lib-py` using pip:

```python
pip install atlas-local-lib-py
```

### Create or Reuse a Deployment

Use the following Python code to create a new local database deployment or reuse an existing one with matching configuration:

```python
from atlas_local import LocalDeployment

# Create or reuse a deployment named "my-local-deployment"
deployment = LocalDeployment.get_or_create(
    name="my-local-deployment"
)

# Get the connection string
connection_string = deployment.connection_string()
print(f"Connection string: {connection_string}")
```

The `get_or_create()` method:

- Creates a new deployment if one with the specified name doesn't exist

- Reuses an existing deployment if one with the specified name already exists

- Returns a `LocalDeployment` object that you can use to manage the deployment

- Automatically handles the Docker container lifecycle

### Load Sample Data

Use the following python method to load MongoDB sample data into your deployment:

```python
from atlas_local import LocalDeployment

deployment = LocalDeployment.get_or_create(
    name="my-local-deployment"
)

# Load sample data
deployment.load_sample_data()
```

For more information about the Python library, see the [atlas-local-lib-py repository.](https://github.com/mongodb/atlas-local-lib-py)

## Manage a Local Atlas Deployment

Use the `atlas local` command to manage a local Atlas deployment.

1. List the available deployments.

   **Example:**

   ```sh
   atlas local list
   ```

   **Output:**

   ```sh
   NAME        TYPE    MDB VER   STATE
   local50     LOCAL   7.0.1     IDLE
   local62     LOCAL   7.0.1     IDLE
   myLocalRs   LOCAL   7.0.1     IDLE
   myLocalRs1  LOCAL   7.0.1     IDLE
   ```

2. Load sample data.

   **Note:**

   You can also load sample data during deployment setup using the `--loadSampleData true` option with `atlas local
               setup`. See the setup examples above.

   To load sample data into an existing deployment:

   Run the following command to download the sample data:

   ```sh
   curl  https://atlas-education.s3.amazonaws.com/sampledata.archive -o sampledata.archive
   ```

   Get the port number for your deployment by running the following command and selecting your deployment:

   ```sh
   atlas local connect --connectWith connectionString
   ```

   The connection string includes the port number. For example, in the connection string `mongodb://localhost:27017/?directConnection=true`, the port number is `27017`.

   Get the port number for your deployment:

   Copy the following command:

   ```sh
   atlas local connect <deployment name> --connectWith connectionString
   ```

   Replace `<deployment name>` with the name of your deployment.

   Run the command.

   The connection string includes the port number. For example, in the connection string `mongodb://localhost:27017/?directConnection=true`, the port number is `27017`.

   Copy and paste the following command into your terminal and replace `{port-number}` with the port for your deployment:

   ```sh
   mongorestore --archive=sampledata.archive --port={port-number}
   ```

3. Connect to a deployment.

   Run the following command to connect to a deployment:

   ```sh
   atlas local connect
   ```

   Specify the deployment to connect to and press Enter.

   Specify how you want to connect to the deployment and press Enter.

   You can retrieve the connection string or connect to the following clients: connection string:

   - [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) if you installed [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh)

   - MongoDB Compass if you installed [Compass](https://www.mongodb.com/docs/compass/current/)

   - Visual Studio Code if you installed [Visual Studio Code](https://code.visualstudio.com/download), [Visual Studio Code CLI](https://code.visualstudio.com/download), and [MongoDB for VS Code Extension](https://www.mongodb.com/docs/mongodb-vscode/install/)

4. Pause a deployment.

   Run the following command to pause a deployment:

   ```sh
   atlas local stop
   ```

   Specify the deployment to pause and press Enter.

5. Start a deployment

   Run the following command to start a deployment:

   ```sh
   atlas local start
   ```

   Specify the deployment to start and press Enter.

6. Return the logs for the deployment.

   Run the following command to return the logs for a deployment:

   ```sh
   atlas local logs
   ```

   Specify the deployment to return logs for and press Enter.

## Delete an Atlas Deployment

1. Run the following command to delete a deployment:

   ```sh
   atlas local delete
   ```

2. Specify the deployment to delete and press Enter.

3. Specify `y` and press Enter. to confirm.

## Move a Local Atlas Deployment to a Cloud Atlas Deployment

You can use [Docker](https://www.docker.com/) and [MongoDB Database Tools](https://www.mongodb.com/docs/database-tools/installation/installation/) to move a local Atlas deployment to a cloud Atlas deployment.

1. Create a cloud Atlas deployment.

   ```sh
   atlas setup
   ```

2. Create a local Atlas deployment.

   ```sh
   atlas local setup
   ```

   To initialize the local Atlas deployment with your own data and indexes:

   Copy the following command:

   ```sh
   atlas local setup --initdb {folder}
   ```

   Replace the `{folder}` placeholder with the directory that contains the `.js` and `.sh` files to run inside the local container in alphanumeric order.

   Run the command.

3. Create a binary file of the data.

   Copy the following command:

   ```sh
   docker exec -u root -it {local_deployment_name} sh -c "mkdir -p /data/dump && chown -R mongod:mongod /data/dump && mongodump --archive=/data/dump/dump.archive"
   ```

   Replace the `{local-deployment-name}` placeholder with the name of your local Atlas deployment.

   Run the command.

4. Copy the archive.

   Copy the following command:

   ```sh
   docker cp <local deployment name>:/data/dump/dump.archive .
   ```

   Replace the `{local-deployment-name}` placeholder with the name of your local Atlas deployment.

   Run the command.

5. Return the connection string.

   ```sh
   atlas clusters connectionStrings describe
   ```

6. Restore from the archived file.

   Copy the following command:

   ```sh
   mongorestore --uri={connection-string} --archive=./dump.archive
   ```

   Replace the `{connection-string}` placeholder with the connection string.

   Run the command.

7. (Optional) Delete the local Atlas deployment.

   ```sh
   atlas local delete
   ```

## Update a Local Atlas Deployment

You can use [Docker](https://www.docker.com/) and [MongoDB Database Tools](https://www.mongodb.com/docs/database-tools/installation/installation/) to update a local Atlas deployment to a newer version of the image.

1. Create a new local Atlas deployment.

   ```sh
   atlas local setup
   ```

   To initialize the local Atlas deployment with your own data and indexes:

   Copy the following command:

   ```sh
   atlas local setup --initdb {folder}
   ```

   Replace the `{folder}` placeholder with the directory that contains the `.js` and `.sh` files to run inside the local container in alphanumeric order.

   Run the command.

2. Create a binary file of the data.

   Copy the following command:

   ```sh
   docker exec -u root -it {old-local-deployment-name} sh -c "mkdir -p /data/dump && chown -R mongod:mongod /data/dump && mongodump --archive=/data/dump/dump.archive"
   ```

   Replace the `{old-local-deployment-name}` placeholder with the name of your old local Atlas deployment.

   Run the command.

3. Copy the archive.

   Copy the following command:

   ```sh
   docker cp {old-local-deployment-name}:/data/dump/dump.archive .
   ```

   Replace the `{old-local-deployment-name}` placeholder with the name of your old local Atlas deployment.

   Run the command.

4. Return the new connection string.

   ```sh
   atlas local connect --connectWith connectionString
   ```

5. Restore from the archived file.

   Copy the following command:

   ```sh
   mongorestore --uri={connection-string} --archive=./dump.archive
   ```

   Replace the `{connection-string}` placeholder with the connection sring.

   Run the command.

6. (Optional) Delete the old local Atlas deployment.

   ```sh
   atlas local delete
   ```

## Use MongoDB Search with a Local Atlas Deployment

Use the `atlas local search indexes create` command to create an MongoDB Search search index. You can then run MongoDB Search queries. To learn more, see [MongoDB Search.](https://www.mongodb.com/docs/atlas/atlas-search/)

For detailed steps, see [Create a MongoDB Search Index and Run a Query.](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-fts.md#std-label-atlas-cli-fts-index-query)

## Use MongoDB Vector Search with a Local Atlas Deployment

Use the `atlas local search indexes create` command to work with MongoDB Vector Search. To learn more, see [How to Index Vector Embeddings for Vector Search.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector-search)

For detailed steps, see [Use MongoDB Vector Search with an Atlas Deployment.](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-fts.md#std-label-atlas-cli-deploy-avs)

**Important:**

To use the Atlas CLI with MongoDB Vector Search, you must create an Atlas deployment with MongoDB 7.0.5 or later. If you created a local Atlas deployment with an earlier MongoDB version, you don't get the latest MongoDB version automatically. You must delete the earlier images and deployments. Then you must create a new Atlas deployment.

## Supported Actions

To learn all of the actions that `atlas local` supports, see `atlas-local`.

## Next Steps

After you create and verify your local Atlas deployment, you can:

- **Search your data**: Use MongoDB Search to create and test search indexes in your local deployment. For detailed steps, see [Create a MongoDB Search Index and Run a Query.](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-fts.md#std-label-atlas-cli-fts-index-query)

- **Use MongoDB Vector Search**: Create vector search indexes and run queries. For detailed steps, see [Use MongoDB Vector Search with an Atlas Deployment.](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-fts.md#std-label-atlas-cli-deploy-avs)

- **Load custom data**: Initialize your deployment with your own datasets using the `--initdb` flag. See [Create a Local Atlas Deployment](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-local.md#std-label-atlas-cli-deploy-local-setup) for details.

- **Manage your deployment**: List, connect, pause, start, or delete deployments. See [Manage a Local Atlas Deployment.](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-local.md#std-label-atlas-cli-deploy-local-manage)

- **Move to Atlas cloud**: Migrate your local deployment to a cloud deployment. See [Move a Local Atlas Deployment to a Cloud Atlas Deployment.](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-local.md#std-label-atlas-cli-move-local-to-cloud)

## Troubleshoot Errors

To learn more about troubleshooting local Atlas deployment issues, see [Troubleshoot Local Atlas Deployment Issues.](https://www.mongodb.com/docs/atlas/cli/current/troubleshooting.md#std-label-local-deploy-errors)
