How To Use __dirname in Node.js

Working with file paths is a routine part of building applications in Node.js, and __dirname plays an important role in making that process predictable. It provides the absolute path to the directory of the current file, giving developers a stable reference point for loading configuration files, serving static assets, reading templates, and managing logs or uploads. Because it always reflects the location of the file rather than the working directory, it helps avoid many of the subtle bugs that occur when paths are resolved differently across environments.

In this article, we will examine how __dirname works, where it comes from in Node’s module system, and how it compares to related values such as __filename and process.cwd(). We will explore practical use cases, illustrate safe path-building patterns, and look at how to recreate __dirname in ES modules using import.meta.url. We will also review common pitfalls, cross-platform considerations, bundler behavior, and a set of best practices to help you manage paths reliably across modern Node.js projects.

To follow this tutorial, you will need a general knowledge of Node.js. To learn more about Node.js, check out our How To Code in Node.js series.

In Node.js, __dirname is a special built-in variable that always contains the absolute path of the directory where the current JavaScript file resides. It does not change based on where you run the script from; it’s tied to the physical location of the file itself.

For example, if your file is located at:

/Users/alex/projects/app/server.js

then __dirname will be:

/Users/alex/projects/app

You can use it to build file paths safely, especially when reading or writing files relative to your script:

const path = require('path');
const fs = require('fs');

const filePath = path.join(__dirname, 'config.json');
const config = JSON.parse(fs.readFileSync(filePath, 'utf8'));

__dirname reflects the directory location of the current file, not where the Node.js process was started from. This is an important distinction.

For example, if you run a script from another directory:

node ./scripts/start.js

and you log the following inside start.js:

console.log(__dirname);

you’ll still get the path to the scripts folder and not the directory from which you executed the command.

This behavior makes __dirname reliable for resolving resources like configuration files, templates, and static assets located near your code, regardless of how or where the script is executed.

To get the directory where the Node.js process was launched, you’d instead use:

process.cwd();

Node.js provides several ways to identify file and directory paths during runtime, but their behavior can differ depending on how and where your code is executed. Understanding the differences between __dirname, __filename, and process.cwd() helps you handle file operations predictably across environments.

__dirname

As explained earlier, __dirname always points to the folder that contains the current JavaScript file. It doesn’t depend on where the script is executed from.

console.log(__dirname);
// /Users/alex/projects/app

It’s ideal when your script needs to access files relative to its own location; for example, configuration files or templates stored in the same folder.

const path = require('path');
const file = path.join(__dirname, 'config/settings.json');

__filename

__filename provides the absolute path to the current file, including the file name. It’s defined by the same CommonJS wrapper function that defines __dirname.

For example, if your file is /Users/alex/projects/app/server.js, then:

console.log(__filename);
// /Users/alex/projects/app/server.js

This is useful for:

• Logging or debugging (e.g., to identify which file is being executed)
• Building paths that specifically include the file name

You can also extract the directory name using path.dirname(__filename):

const path = require('path');
console.log(path.dirname(__filename)); // same as __dirname

process.cwd()

Unlike the previous two, process.cwd() returns the directory from which the Node.js process was started and not where the current file lives.

If you launch a script from a different directory, process.cwd() will reflect your current shell location, while __dirname and __filename remain tied to the file’s actual path.

Example:

# Directory structure
project/
 ├── app/
 │   └── index.js
 └── run.js

require('./app/index');

console.log('__dirname:', __dirname);
console.log('process.cwd():', process.cwd());

When you run:

node run.js

The output will be:

__dirname: /Users/alex/project/app
process.cwd(): /Users/alex/project

This distinction becomes important when resolving file paths dynamically. Using process.cwd() for relative paths can cause “file not found” errors if the process is started from a different directory.

const path = require('path');
const configPath = path.join(__dirname, 'config', 'app.json');

Here’s a quick overview:

Working with file paths is a common task in Node.js applications. However, constructing paths manually can lead to subtle and hard-to-debug issues, especially when your code needs to run across multiple operating systems. Node’s built-in path module provides utilities like path.join() and path.resolve() that make path handling both safer and platform-independent.

Why You Should Never Manually Concatenate Paths

A common mistake is to concatenate file paths using string operations, such as the + operator or template literals:

// Avoid this
const filePath = __dirname + '/data/config.json';

While this might seem harmless, it introduces several risks:

• Different platforms use different separators. POSIX uses / while Windows uses \. Manually doing dir + '/' + file will break on Windows.
• You can accidentally produce double separators, missing separators, or weird .. and . fragments.
• Manual concatenation encourages insecure patterns when you include untrusted input. For example, "../secret.txt" concatenated into a base path can escape the intended directory.
• path utilities correctly normalize segments, collapse .. and . where appropriate, and handle edge cases like trailing separators and Windows drive letters.

Using Node’s path module solves all of these issues by handling separators and normalization for you.

OS-Safe Path Building with path.join()

path.join() joins all given path segments using the correct platform-specific separator and then normalizes the result. It ensures there are no duplicate slashes and that relative paths are resolved correctly.

Example:

const path = require('path');

const configPath = path.join(__dirname, 'data', 'config.json');
console.log(configPath);

On macOS or Linux:

/Users/alex/project/data/config.json

On Windows:

C:\Users\alex\project\data\config.json

You can also safely join multiple segments, even if some contain leading or trailing slashes:

const logsDir = path.join(__dirname, '/logs/', '/2025/');
console.log(logsDir); // properly normalized path

path.join() always produces a clean, normalized path, regardless of how many slashes or relative segments you include.

Absolute Path Resolution with path.resolve()

While path.join() simply concatenates segments, path.resolve() calculates the absolute path from a sequence of path segments. It simulates how the shell resolves paths, taking into account . (current directory) and .. (parent directory) references.

For example:

const path = require('path');

const absolutePath = path.resolve('data', 'config.json');
console.log(absolutePath);

If your current working directory (process.cwd()) is /Users/alex/project, the output will be:

/Users/alex/project/data/config.json

Unlike path.join(), if any argument passed to path.resolve() is an absolute path, it ignores all previous segments:

path.resolve('/etc', 'config', '/data/logs'); 
// => /data/logs

This makes path.resolve() ideal when you need to ensure that the output path is always absolute, even when combining relative paths.

When to Use Each

Example: Reading a File Safely

Here’s a practical example combining these concepts:

const fs = require('fs');
const path = require('path');

// Safe path construction
const filePath = path.join(__dirname, 'data', 'config.json');

// Reading the file
const config = JSON.parse(fs.readFileSync(filePath, 'utf8'));
console.log(config);

This approach guarantees that the correct file will be read no matter the operating system or how the script is executed. By relying on the path module, you protect your application from file path inconsistencies and ensure that your code runs reliably across different systems.

The following examples show how __dirname helps you load configuration files, serve static assets, and manage directories such as logs and uploads in a predictable and cross-platform way. Each example includes additional detail about how the path is constructed and why the technique is reliable.

Loading configuration files

You can use __dirname to reliably load configuration files stored next to your code, regardless of how or where the application is launched.

If you run a Node.js script from different directories (for example: node app/server.js vs npm start inside another folder), relative paths can break. Configuration files should load consistently no matter how a process is started.

Because __dirname always points to the current file’s directory, it gives you a stable anchor point for reading configuration files such as dev.json, prod.json, or a fallback default.json.

Here’s a simple JSON config loader example:

const fs = require('fs');
const path = require('path');

function loadConfig(env = process.env.NODE_ENV || 'development') {
  const configPath = path.join(__dirname, 'config', `${env}.json`);
  const raw = fs.readFileSync(configPath, 'utf8');
  return JSON.parse(raw);
}

const config = loadConfig('dev'); // loads <project>/config/dev.json

Explanation:

• path.join(__dirname, 'config', `${env}.json`) builds a stable path to config/dev.json, regardless of the working directory.
• The function chooses a config based on the environment and uses synchronous loading for simplicity.
• You avoid fragile patterns like ./config/dev.json, which may break if process.cwd() is different from the project root.

Here’s an optional config with fallback:

function tryLoadConfig(env = 'development') {
  const candidate = path.join(__dirname, 'config', `${env}.json`);
  if (fs.existsSync(candidate)) {
    return JSON.parse(fs.readFileSync(candidate, 'utf8'));
  }
  return JSON.parse(fs.readFileSync(path.join(__dirname, 'config', 'default.json'), 'utf8'));
}

Explanation:

• This pattern is useful when a deployment environment might not provide an environment-specific file.
• By checking fs.existsSync(candidate), you avoid runtime errors when a file is missing.
• __dirname ensures both paths (the candidate and fallback) resolve properly across machines.

Serving static assets (Express example)

You can build the root public directory from __dirname so static files always resolve to the correct location and you avoid exposing unwanted paths.

Static assets should be served from a controlled directory. If you reference the static folder using process.cwd(), starting the app from a different directory may cause Express to serve the wrong folder or fail to find assets.

Using __dirname hardens your asset path so that Express always serves from the intended public folder next to your server code.

Let’s see an Express static middleware example:

const express = require('express');
const path = require('path');

const app = express();
const publicDir = path.join(__dirname, 'public');

app.use(express.static(publicDir));

app.get('/', (req, res) => {
  res.sendFile(path.join(publicDir, 'index.html'));
});

app.listen(3000);

Explanation:

• path.join(__dirname, 'public') establishes a fixed public root path.
• Express uses this directory to serve files safely; anything outside this path is not accessible.
• By combining publicDir with sendFile, you avoid relative path problems that could otherwise load HTML from the wrong location.
• This pattern protects your application from unintentionally exposing code or configuration files.

Working with logs or upload directories

Use __dirname to reference or create directories for runtime data, such as logs or uploads, in a way that does not depend on how the application is started.

If your application generates logs, stores uploads, or writes temporary data, you want these directories to be stable and predictable. Using relative paths tied to process.cwd() can send files to different locations depending on deployment scripts or working directory.

By anchoring log and upload paths with __dirname, you ensure that the filesystem layout behaves consistently across development, staging, CI, and production.

Create a log directory and append to a log file:

const fs = require('fs');
const path = require('path');

const logsDir = path.join(__dirname, 'logs');
const logFile = path.join(logsDir, 'app.log');

fs.mkdirSync(logsDir, { recursive: true });

fs.appendFileSync(logFile, `${new Date().toISOString()} - Server started\n`, 'utf8');

Explanation:

• logsDir is created relative to the code, not the working directory.
• { recursive: true } ensures the directory structure is created even if missing.
• This pattern works in environments where the current working directory may be different, for instance when using PM2, systemd, Docker, or cloud functions.
• Storing logs under the application directory helps keep logs predictable in development and testing.

Safe upload path for user-supplied filenames:

function saveUpload(filename, buffer) {
  const uploadsRoot = path.resolve(__dirname, 'uploads');
  const target = path.resolve(uploadsRoot, filename);

  const rel = path.relative(uploadsRoot, target);
  if (rel.startsWith('..')) {
    throw new Error('Invalid upload path');
  }

  fs.mkdirSync(path.dirname(target), { recursive: true });
  fs.writeFileSync(target, buffer);
}

Explanation:

• uploadsRoot is a canonical path to the uploads folder next to the server code.
• The user-provided filename might contain malicious segments like ../...
• path.resolve(uploadsRoot, filename) merges the root with the user input but produces an absolute path.
• The relative comparison prevents paths that escape the allowed folder.
• By writing files only after validation, you avoid overwriting other files in your project or operating system.

Node.js behaves differently when your project uses ES modules (.mjs files or "type": "module" in package.json). In this environment, the CommonJS wrapper function is no longer used, which means __dirname and __filename are not available.

In ES module mode, Node does not inject the CommonJS wrapper function that normally provides:

• exports
• require
• module
• __filename
• __dirname

If you try to access __dirname inside an ES module, you will see an error like:

ReferenceError: __dirname is not defined in ES module scope

This behavior is intentional and part of the module system design.

Why Node removed them in ES modules

The ES module specification is defined by the JavaScript standard and does not include __dirname or __filename. These values were created specifically for CommonJS and rely on the wrapper function that Node uses around every .js file in CJS.

ES modules load and execute differently:

• They are evaluated using URLs (not filesystem paths).
• They support both file URLs and non-file URLs (such as network locations).
• They do not get wrapped by a function that injects helper variables.

To keep ES modules standards-compliant and interoperable with browsers, Node avoided introducing __dirname and __filename into the ESM world.

Instead, ES modules provide a built-in mechanism that works across environments: import.meta.url.

Introducing import.meta.url

When you need the equivalent of __dirname or __filename in an ES module, you use import.meta.url. It contains the full URL to the current module file, such as:

file:///Users/alex/project/src/server.mjs

Unlike __dirname, this value is a URL string, not a plain file path. To convert it into a filesystem path, you use the fileURLToPath helper from the url module.

// server.mjs
import { fileURLToPath } from 'url';
import { dirname } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

console.log(__dirname);
// /Users/alex/project/src

Here, import.meta.url provides the complete URL pointing to the current module file, and fileURLToPath() converts that file:// URL into a standard filesystem path that Node’s fs and path modules can work with. Once you have the full file path, calling path.dirname() extracts the directory portion, giving you a stable __dirname equivalent that behaves much like it does in CommonJS modules.

You now have usable equivalents of both __dirname and __filename inside an ES module.

Here’s a simple example of reading a configuration file in an ES module:

import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const configPath = path.join(__dirname, 'config', 'dev.json');
const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));

console.log(config);

This approach works because import.meta.url is the standard way ES modules expose a module’s location. Converting that URL to a filesystem path with fileURLToPath() gives you the same stable information that CommonJS provided through __filename and __dirname, but without relying on Node’s wrapper function. It keeps the behavior explicit, standards-aligned, and compatible with tools and environments that expect ES module semantics.

Working with file paths in Node.js becomes intuitive once you understand how module systems, operating systems, and tooling interact. Still, several recurring issues tend to frustrate developers, especially when switching between CommonJS and ES modules, running code through bundlers, or deploying across platforms. The following sections describe these issues in more depth, explain why they appear, and show patterns that help you avoid them in real projects.

__dirname is not defined in ES module scope

This is usually the first obstacle developers hit after switching from CommonJS to ES modules. Since ES modules follow the JavaScript specification, Node does not wrap modules in a function and therefore doesn’t inject special variables like __dirname or __filename. Instead, each ES module exposes its location through import.meta.url, which uses a URL rather than a plain file path. Converting that URL into a filesystem path lets you recreate both __filename and __dirname:

import { fileURLToPath } from 'url';
import path from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

Once you have these values, you can use them anywhere you would have used their CommonJS equivalents, such as loading configuration files, reading templates, or resolving static assets. This pattern also behaves consistently in worker threads that use ESM, making it safe for distributed and multi-process applications.

Path surprises when using bundlers (Webpack, Vite, Rollup) and tools like ts-node

Bundlers introduce a layer of abstraction between your source code and the resulting output. This can alter how paths behave. For example, Webpack may replace __dirname with '/' unless told to preserve Node behavior. Vite and Rollup, on the other hand, treat import.meta.url as a static value and may inline it or rewrite it during bundling. These transformations can break runtime assumptions, especially if your application needs to load files from disk.

For server-side bundles, it helps to instruct the bundler to retain Node semantics:

// webpack.config.js
module.exports = {
  target: 'node',
  node: {
    __dirname: false,
    __filename: false
  }
};

In browser-oriented bundles, you cannot rely on filesystem access at all. Instead, use standards-based asset resolution:

const imageUrl = new URL('./logo.png', import.meta.url).href;

ts-node can also change behavior depending on whether it runs in ESM mode, CommonJS mode, or hybrid mode. If you rely on path-specific behavior (for example, loading templates from disk), verify your TypeScript configuration matches your expectations. Aligning "module", "moduleResolution", and "type": "module" ensures that the runtime and compiler agree on how paths should behave.

Windows and POSIX path inconsistencies

Path handling differences between Windows and POSIX systems frequently cause subtle, hard-to-track bugs. Windows uses backslashes and drive letters, and comparisons may be case-insensitive. POSIX systems use forward slashes and treat paths strictly as case-sensitive strings. Many issues arise when code assumes one environment: for example, checking whether a path starts with '/' to test whether it is absolute, or comparing strings directly instead of resolving them.

Using the path module avoids these differences:

const fullPath = path.join('logs', 'app.log');

This produces a correct separator on any platform. If you need to compare paths, convert both to their absolute, normalized forms:

const a = path.resolve(userInput);
const b = path.resolve(basePath);

On Windows, you may normalize casing to ensure consistent comparisons. For situations where code must emit POSIX-friendly paths (for example, when generating URLs, Docker paths, or configuration files for cross-platform tools), use path.posix.*:

const posixPath = path.posix.join('data', 'inputs', 'file.csv');

This approach sidesteps platform-specific rules and keeps your logic portable across development, CI, and production.

When relative paths point to the wrong place

Relative paths are resolved against the current working directory, not the directory of the file that declares them. This works fine during local development but fails easily once the application runs under a service manager, inside a Docker container, or in a CI pipeline. A file such as ./config/settings.json might load correctly in one environment but fail in another because process.cwd() changed.

To avoid this, anchor paths to the file location rather than the working directory:

const settingsPath = path.join(__dirname, 'config', 'settings.json');

In ES modules, use:

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const settingsPath = path.join(__dirname, 'config', 'settings.json');

This keeps file resolution consistent, no matter how the application is launched. It is especially important for config loading, template rendering, migrations, test fixtures, and static asset directories.

REPL and worker thread differences

The Node REPL runs code outside of a module context, so values like __dirname and __filename are not available. This often surprises developers who paste snippets directly into the REPL. If you need directory information in a REPL session, generate it explicitly:

const path = require('path');
const here = path.resolve('.');

Worker threads inherit the behavior of the module type they execute. A worker launched with a .mjs file behaves like any other ES module and relies on import.meta.url. A worker launched as CommonJS exposes __dirname normally. Because worker threads do not always share the same working directory, pass absolute paths into the worker to avoid ambiguity:

new Worker('./worker.mjs', {
  workerData: {
    basePath: path.resolve(__dirname)
  }
});

This ensures the worker always knows where your files are located, regardless of how or where it was spawned.

Writing path utilities that are easy to test

Path-heavy code is more testable when it depends on explicit inputs rather than globals. Instead of hardcoding __dirname inside utility functions, pass the base directory as a parameter. This makes the utilities reusable and far easier to validate in automated tests:

export function loadConfig(baseDir, name) {
  const fullPath = path.join(baseDir, 'config', `${name}.json`);
  return JSON.parse(fs.readFileSync(fullPath, 'utf8'));
}

In production, use:

loadConfig(__dirname, 'dev');

In tests, use:

loadConfig(tmpDir, 'dev');

For upload paths or other security-critical operations, keep validation logic centralized:

export function safeResolve(base, target) {
  const root = path.resolve(base);
  const resolved = path.resolve(root, target);
  const rel = path.relative(root, resolved);

  if (rel.startsWith('..')) {
    throw new Error('Path escapes base directory');
  }
  return resolved;
}

This design prevents directory traversal and makes your tests predictable, since you can assert expected behavior by passing in controlled test directories and inputs.

By understanding how different environments treat path resolution and applying these patterns consistently, you can avoid most of the subtle bugs that arise when working with files across CommonJS, ES modules, worker threads, bundlers, and different operating systems.

Working with file paths becomes much simpler and more reliable when you follow a small set of habits consistently. These practices help you avoid platform differences, prevent accidental mis-resolution, and allow your codebase to scale without accumulating path-related issues.

Always pair paths with path.join()

Constructing paths with string concatenation often leads to subtle bugs, especially when switching between Windows and POSIX systems. Using path.join() (and path.resolve() when absolute paths are required) ensures separators are correct and that relative segments are normalized. For example:

const full = path.join(__dirname, 'config', 'dev.json');

This approach produces stable paths across all environments, keeps the code readable, and removes the guesswork around trailing or leading slashes.

Avoid hardcoding absolute paths

Hardcoded absolute paths frequently break when deployed on different machines, containers, or cloud environments. They also make tests and CI pipelines brittle. Rather than referencing something like /usr/local/app/config.json, anchor paths to the module location in CommonJS or derive them from import.meta.url in ES modules:

const configPath = path.join(__dirname, 'config', 'app.json');

This ensures your code works regardless of where the project is checked out or how the process is started.

Prefer ESM patterns in modern projects

Modern Node.js encourages the ES module standard, which uses import and export and relies on import.meta.url for module location. This pattern is clearer, more explicit, and interoperates better with browser tooling and modern build systems. Recreating __dirname and __filename through:

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

keeps your code compatible with the direction the ecosystem is moving, while still allowing you to load configuration files, templates, and static assets in a predictable way.

Wrap path logic in reusable utilities

Repeatedly converting import.meta.url, resolving user input, and validating directory boundaries can introduce duplication and inconsistencies. Wrapping this behavior into utilities helps keep your codebase clean and makes the logic easier to test. For example:

export function moduleDir(metaUrl) {
  return path.dirname(fileURLToPath(metaUrl));
}

export function safeResolve(base, target) {
  const root = path.resolve(base);
  const resolved = path.resolve(root, target);
  const rel = path.relative(root, resolved);

  if (rel.startsWith('..')) {
    throw new Error('Path escapes base directory');
  }
  return resolved;
}

By centralizing this logic, you can audit path handling in one place instead of chasing issues across multiple modules. It also gives your tests stable boundaries, since the utilities accept explicit inputs rather than relying on global behavior.

Using these best practices consistently produces predictable, cross-platform path resolution, reduces bugs caused by implicit assumptions, and makes your application easier to maintain across environments and tooling setups.

1. What does __dirname do in Node.js?

__dirname is a built-in variable available in CommonJS modules that returns the absolute path of the directory that contains the current file. It always reflects the file’s physical location on disk, not the directory from which the Node.js process was launched. Developers commonly use it to build stable paths for configuration files, templates, logs, and static assets.

2. How is __dirname different from process.cwd()?

__dirname points to the directory of the current file, while process.cwd() returns the working directory where Node.js was executed. This distinction is important because the working directory can change depending on how the process is launched. Code that uses process.cwd() for file loading can break in production if the process starts in a different location. __dirname is more reliable for loading resources that sit next to your script.

3. How do I use __dirname in ES Modules?

ES modules do not provide __dirname automatically. Instead, you reconstruct it from the module URL. This is the standard pattern:

import { fileURLToPath } from 'url';
import path from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

Once defined, you can use __dirname just as you would in CommonJS.

4. Why is __dirname not defined in Node.js?

__dirname is only defined inside CommonJS modules. If your project uses ES modules (for example, via "type": "module" in package.json or .mjs file extensions), Node.js follows the ECMAScript specification and does not inject CommonJS-specific variables like __dirname or require. ES modules use import.meta.url instead to represent the module’s location.

5. How can I get the current directory in Node.js?

There are two ways to get a directory path, and they behave differently:

1. To get the directory of the current file in ES Modules:

   const __dirname = path.dirname(fileURLToPath(import.meta.url));
   

   or in CommonJS:

   console.log(__dirname);
   

2. To get the current working directory of the process:

   console.log(process.cwd());
   

Use the first approach for file-relative paths (templates, configs). Use the second for command-line tools or scripts that should depend on where the user ran the command.

6. What’s the difference between __dirname and __filename?

__dirname gives you the path to the current directory, while __filename gives you the full absolute path to the file itself. For example, if your file is located at:

/Users/dev/project/src/server.js

then __dirname will give you /Users/dev/project/src, whereas __filename will give you /Users/dev/project/src/server.js.

Developers often use __filename for logging or for computing the directory name using path.dirname(__filename).

__dirname is one of the most dependable tools for working with file paths in Node.js because it always reflects the actual location of the current file. By understanding how it differs from process.cwd(), how it relates to __filename, and how to recreate it in ES modules using import.meta.url, you gain a clear, consistent way to load resources such as configuration files, templates, logs, uploads, and static assets. Pairing __dirname with the path module gives you predictable, cross-platform path handling, while the patterns covered in this guide help you avoid common pitfalls across module systems, operating systems, bundlers, and test environments.

To learn more about Node.js, check out the following articles:

• Introduction to the Path Module in Node.js
• How To Create a Web Server in Node.js with the HTTP Module
• How To Launch Child Processes in Node.js