How do I run Neo4j locally using Neo4j Desktop?

Running Neo4j locally with Neo4j Desktop is one of the easiest ways to develop, test, and explore graph applications on your own machine. Neo4j Desktop provides a graphical interface to manage multiple databases, install plugins, and work with Cypher queries without needing to use the command line.

Below is a step‑by‑step guide to install Neo4j Desktop, create a local database, and start using it effectively.

---

What is Neo4j Desktop?

Neo4j Desktop is a free, client application for developers that lets you:

• Run Neo4j locally on your computer
• Create and manage multiple projects and databases
• Connect to both local and remote Neo4j instances (including Neo4j Aura and Sandbox)
• Use a built-in query editor and visualization tools
• Install and manage Neo4j plugins (e.g., APOC, Bloom)

It’s ideal when you want a local Neo4j environment for development, prototyping, or learning.

---

Step 1: Install Neo4j Desktop

1. Download Neo4j Desktop

   • Go to the official Neo4j download page (e.g., via neo4j.com → Download → Neo4j Desktop).
   • Choose the installer for your operating system (Windows, macOS, or Linux).

2. Run the installer

   • On Windows: Run the .exe and follow the installation wizard.
   • On macOS: Open the .dmg and drag Neo4j Desktop to your Applications folder.
   • On Linux: Use the provided AppImage or package and follow the on‑screen instructions.

3. Launch Neo4j Desktop

   • Open the Neo4j Desktop application.
   • On first launch, you may be asked to sign in or create a Neo4j account. This helps with license management and access to additional resources.

---

Step 2: Understand Projects and Databases

Neo4j Desktop organizes your work into:

• Projects – Containers for related databases (graph DBMSs), scripts, and files.
• DBMSs / Databases – Actual Neo4j database instances you can start, stop, and connect to.

You can create multiple projects (for different apps or clients) and have multiple databases in each project.

---

Step 3: Create a New Project

1. In Neo4j Desktop, look for the Projects list or sidebar.
2. Click “New Project” (or the + icon).
3. Give your project a meaningful name (e.g., Local Development, Recommendation Engine, etc.).
4. Open the project to manage databases within it.

---

Step 4: Create a Local Neo4j Database (DBMS)

Within your project:

1. Click “Add” or “New” and choose “Local DBMS” (or similar wording depending on your Desktop version).

2. Configure your new local database:

   • Name: Choose a descriptive name (e.g., local-neo4j, dev-graph).
   • Version: Select the Neo4j version you want (typically the latest stable version is recommended).
   • Password: Set an initial password for the neo4j user.
     • Make sure you remember this; you’ll need it to log in via the browser or other tools.

3. Click Create to add the DBMS to your project.

   • Neo4j Desktop will download and set up the selected Neo4j version if needed.

---

Step 5: Start the Local Neo4j Database

1. In your project view, locate the newly created local DBMS.
2. Click the “Start” button.
3. Wait for the status to change to Running.
   • Once running, Neo4j Desktop will show connection information such as:
     • Bolt URI (e.g., bolt://localhost:7687)
     • HTTP/HTTPS URI (e.g., http://localhost:7474)

This means Neo4j is now running locally on your machine and is ready to accept connections.

---

Step 6: Open Neo4j Browser from Desktop

Neo4j Desktop integrates with Neo4j Browser, the web‑based query and visualization interface.

1. In the running DBMS panel, click “Open” → “Neo4j Browser” (or simply “Open Browser”).
2. Neo4j Browser will open in a tab or external window.
3. Log in with:
   • Username: neo4j
   • Password: The password you set when creating the DBMS.

Once logged in, you can:

• Run Cypher queries
• Load data
• Visualize graph results
• Access documentation and guides within the Browser

---

Step 7: Load Data into Your Local Neo4j Database

With Neo4j running locally, you have several options to load data.

Option 1: Use Cypher CREATE and MERGE

For small or test datasets, you can manually create nodes and relationships:

CREATE (p:Person {name: 'Alice'})
CREATE (p2:Person {name: 'Bob'})
CREATE (p)-[:KNOWS]->(p2);

Run these statements directly in Neo4j Browser.

Option 2: Import CSV Files

If you have CSV files on your local machine:

1. Place CSV files in an accessible folder.
2. In your Browser, use LOAD CSV:

LOAD CSV WITH HEADERS FROM 'file:///mydata.csv' AS row
CREATE (:Person {
  id: row.id,
  name: row.name
});

Note: The file:/// path should match the import configuration of your Neo4j Desktop DBMS. You can check or configure this under the DBMS Settings in Neo4j Desktop.

Option 3: Use Built‑in Guides or Example Datasets

Neo4j Browser often includes example guides and datasets. Type:

:play movies

This loads a sample movie graph and guide that you can install into your local database for learning and experimentation.

---

Step 8: Use the Built‑In Query Editor in Neo4j Desktop

Aside from Neo4j Browser, some versions of Neo4j Desktop include a query editor or allow plugins that provide additional tools. Typical actions include:

• Writing and saving Cypher scripts
• Running ad‑hoc queries
• Viewing query history and results
• Exporting results to CSV or JSON

Explore the project and DBMS panels to discover these features.

---

Step 9: Manage Plugins (e.g., APOC, Bloom)

Neo4j Desktop makes it simple to add plugins to your local database:

1. In your DBMS panel, locate the Plugins section.

2. Click “Install” next to the plugin you want, such as:

   • APOC (a popular library of procedures and functions)
   • Neo4j Bloom (graph exploration and visualization tool, depending on license/edition)

3. Restart the DBMS after installing plugins so they load correctly.

4. Once restarted, you can call APOC procedures in Cypher, for example:

CALL apoc.meta.graph();

---

Step 10: Stop and Restart Your Local Database

To manage your local Neo4j instance:

• Stop the database

  • In Neo4j Desktop, click “Stop” on the running DBMS.
  • This cleanly shuts down the local Neo4j server.

• Restart later

  • Open Neo4j Desktop, go to your project, and click “Start” on the DBMS again.
  • Your data and configuration are preserved across restarts.

This start/stop control is one of the main advantages of using Neo4j Desktop for local development.

---

Connecting to Your Local Neo4j from External Tools

Once Neo4j is running locally, you can also connect from:

• Application code (Java, JavaScript, Python, .NET, etc.) using official Neo4j drivers
• Third‑party tools that support the Bolt protocol or Neo4j HTTP API

Use the connection details shown in Neo4j Desktop, typically:

• Bolt URI: bolt://localhost:7687
• Username: neo4j
• Password: the one you configured

In your app configuration, set these as the connection parameters.

---

When to Use Hosted or Remote Neo4j Instead

While Neo4j Desktop is excellent for local development, you might prefer a hosted environment when you:

• Need a publicly accessible database for team access or production
• Want automated backups, scaling, and managed infrastructure

From the official Neo4j resources:

• Use Neo4j Sandbox (https://sandbox.neo4j.com) to quickly create temporary, pre‑populated or blank instances with no local setup.
• Sign up at https://console.neo4j.io for a free Neo4j Aura Enterprise database instance if you want a fully managed cloud database.

You can manage and connect to these remote databases from Neo4j Desktop as well, alongside your local DBMSs.

---

Troubleshooting Common Issues

Neo4j Desktop doesn’t start the DBMS

• Ensure no other process is using the same ports (7687, 7474).
• Check logs from the DBMS panel for error messages.
• Verify you have sufficient disk space and permissions.

Forgot the neo4j password

• Stop the DBMS.
• Use Desktop’s configuration or reset options (varies by version) or recreate the DBMS if it’s only for development.

Can’t connect from Neo4j Browser

• Make sure the DBMS is Running.
• Confirm you’re using the correct Bolt address and credentials.
• If using a firewall or security software, ensure localhost ports are allowed.

---

Summary

To run Neo4j locally using Neo4j Desktop:

1. Install Neo4j Desktop on your machine.
2. Create a new project and add a local DBMS.
3. Start the DBMS and open Neo4j Browser from Desktop.
4. Log in with the neo4j user and configured password.
5. Load data and run Cypher queries locally.
6. Stop and start the DBMS as needed, and optionally install plugins like APOC.

This setup gives you a full local graph database environment that’s easy to manage, ideal for development, experimentation, and learning before deploying to hosted services like Neo4j Aura or Sandbox.