The separator trap
You write a script to scan a directory for log files. It works perfectly on your Linux laptop. You send it to a teammate on Windows, and they get a wall of errors. The paths look wrong. Or you're building a web server and need to construct a URL path, but you accidentally use the file system logic, and now your URLs contain backslashes that break the browser. Go splits path handling into two packages to keep these worlds separate.
Go started on Unix. Unix uses forward slashes. The path package reflects that heritage. When Go expanded to Windows, the team added path/filepath to handle backslashes and drive letters without changing the behavior of path. This preserves compatibility and keeps the mental model clean: path is for the abstract, filepath is for the concrete.
Think of path as a coordinate system that never changes. It always uses forward slashes. It treats every string as a sequence of segments separated by /. It doesn't care about drive letters, case sensitivity, or what operating system is running the code. path is for URLs, tar archives, zip files, and any text-based format where the path structure is part of the protocol, not the host machine.
Think of filepath as a map that adapts to the terrain. It checks the operating system and uses the correct separator. On Windows, it uses backslashes. On Linux and macOS, it uses forward slashes. It also understands volumes like C: on Windows. filepath is for anything that touches the disk: opening files, walking directories, checking permissions, or constructing paths for system calls.
Minimal example: Joining paths
The difference shows up immediately when you join segments. path.Join always produces forward slashes. filepath.Join produces the separator your OS expects.
package main
import (
"fmt"
"path"
"path/filepath"
)
// ComparePaths demonstrates the difference between URL-style and OS-aware path joining.
func ComparePaths() {
// path.Join always uses forward slashes, regardless of the OS.
// This is safe for URLs, tar archives, or any text-based path format.
urlStyle := path.Join("assets", "images", "logo.png")
fmt.Println("URL style:", urlStyle)
// filepath.Join uses the OS-specific separator.
// On Windows this produces "assets\images\logo.png".
// On Linux/macOS this produces "assets/images/logo.png".
osStyle := filepath.Join("assets", "images", "logo.png")
fmt.Println("OS style:", osStyle)
}
The compiler treats both packages as simple string manipulators. There is no type distinction. A string is a string. The difference appears at runtime. filepath functions consult os.PathSeparator to decide which character to insert. path functions hardcode /. This means filepath.Join("a", "b") returns a/b on Linux and a\b on Windows. path.Join("a", "b") returns a/b everywhere.
The runtime also handles volumes differently. filepath recognizes that C: is a volume prefix. path treats C: as just another segment. If you pass C:\Users to path.Join, it might mangle the drive letter because it doesn't know C: is special. filepath preserves the volume structure.
Forward slashes are universal. Backslashes are local.
Absolute paths and volumes
The packages diverge further when dealing with absolute paths. path.IsAbs checks only for a leading slash. filepath.IsAbs checks for a leading slash on Unix or a volume prefix on Windows.
// CheckAbs shows how absolute path detection differs between packages.
func CheckAbs() {
// path.IsAbs only recognizes leading slashes.
// It treats "C:\Users" as a relative path because it lacks a leading slash.
fmt.Println("path.IsAbs(\"C:\\\\Users\"):", path.IsAbs(`C:\Users`))
// filepath.IsAbs understands Windows volumes.
// It correctly identifies "C:\Users" as absolute on Windows.
// On Linux, it would return false because volumes don't exist.
fmt.Println("filepath.IsAbs(\"C:\\\\Users\"):", filepath.IsAbs(`C:\Users`))
// filepath.VolumeName extracts the drive letter on Windows.
// path has no equivalent function because it has no concept of volumes.
vol := filepath.VolumeName(`C:\Users\file.txt`)
fmt.Println("Volume:", vol)
}
Using path.IsAbs on a Windows path like C:\Data returns false. If your code relies on that check to decide whether to resolve a path, it will fail silently on Windows. The path remains relative, and subsequent operations might look in the wrong directory. The compiler won't warn you. You'll get a runtime error like open C:\Data: no such file or directory when the program tries to treat an absolute path as relative.
filepath.Clean also handles volumes correctly. It normalizes the path without stripping the drive letter. path.Clean might treat the volume as a segment and produce unexpected results. Always use filepath.Clean for disk paths.
Convention aside: The Go community treats filepath as the default for file I/O. If you aren't sure which package to use, pick filepath. It's safer for disk operations. Using path for files is a code smell that suggests the code hasn't been tested on Windows.
Pattern matching and case sensitivity
File matching reveals another layer of OS awareness. filepath.Match respects the case sensitivity rules of the host system. path.Match is always case-sensitive.
On Windows, the file system is case-insensitive. filepath.Match("*.txt", "Report.TXT") returns true. On Linux, the file system is case-sensitive. filepath.Match("*.txt", "Report.TXT") returns false. path.Match returns false on both systems because it implements POSIX-style matching.
This matters when you build glob patterns for user input. If you use path.Match to validate a filename on Windows, you might reject a valid file because the case doesn't match exactly. If you use filepath.Match, the validation aligns with what the OS will actually find.
Use filepath.Glob for finding files on disk. It uses filepath.Match internally, so it inherits the OS-aware behavior. Use path.Match only when you are matching strings that follow a strict protocol, like URL patterns where case matters.
Case sensitivity is part of the path contract. Trust filepath to handle it.
Realistic example: Building a static site generator
A static site generator needs to walk the file system to find content files and generate URLs for them. This requires both packages. filepath handles the disk traversal. path handles the URL construction. The conversion happens at the boundary.
package main
import (
"fmt"
"os"
"path"
"path/filepath"
)
// ProcessAssets finds files in a directory and generates web URLs for them.
// It uses filepath for disk operations and path for URL construction.
func ProcessAssets(rootDir string) ([]string, error) {
// filepath.Abs resolves the directory relative to the current working directory.
// This ensures we have a full path for the file system.
absRoot, err := filepath.Abs(rootDir)
if err != nil {
return nil, fmt.Errorf("resolve directory: %w", err)
}
// filepath.WalkDir traverses the directory tree using OS-aware paths.
// It handles symlinks and permissions correctly for the host OS.
var urls []string
err = filepath.WalkDir(absRoot, func(p string, d os.DirEntry, err error) error {
if err != nil {
return err
}
if d.IsDir() {
return nil
}
// filepath.Rel computes the relative path from absRoot to p.
// This gives us the path structure without the full OS prefix.
rel, err := filepath.Rel(absRoot, p)
if err != nil {
return fmt.Errorf("relative path: %w", err)
}
// filepath.ToSlash converts OS separators to forward slashes.
// On Windows, rel contains backslashes. URLs must use forward slashes.
// Without this, path.Join would treat backslashes as regular characters.
relSlash := filepath.ToSlash(rel)
// path.Clean ensures the URL path has no ".." or "." segments.
// We use path here because URLs must use forward slashes.
cleanURL := path.Join("/static", path.Clean(relSlash))
urls = append(urls, cleanURL)
return nil
})
if err != nil {
return nil, fmt.Errorf("walk directory: %w", err)
}
return urls, nil
}
Notice filepath.ToSlash. The filepath.Rel function returns a path using the OS separator. On Windows, that means backslashes. URLs must use forward slashes. filepath.ToSlash converts the result so path.Join can work correctly. Without this conversion, the URLs would contain backslashes, and browsers would reject them. path.Join does not treat backslashes as separators. path.Join("/static", "a\\b") produces /static/a\\b, which is invalid.
The code also uses filepath.Abs to normalize the root directory. This prevents issues with relative paths like ./src that might resolve differently depending on where the script is run. filepath.Abs returns a path that os.Open can use reliably.
Mix the packages intentionally. Convert at the boundary.
Pitfalls and runtime failures
Using filepath for URLs is the most common mistake. If you use filepath.Join to build a URL on Windows, the result contains backslashes. The compiler won't catch this. You'll get a runtime error when the browser fails to fetch the resource, or the server returns a 404 because the routing logic expects forward slashes. The error message looks like 404 Not Found: /assets\logo.png. The backslash is invisible in the code but fatal in the network request.
Using path for file system operations is riskier on Windows. Go's os package often accepts forward slashes on Windows, but this is an implementation detail, not a guarantee. Some system calls or third-party libraries might fail if the path contains forward slashes. Relying on path for file I/O creates fragile code that breaks when the environment changes. Always use filepath for disk paths.
Another trap is filepath.Join with absolute paths. If you pass an absolute path as an argument, filepath.Join discards all previous segments and returns the absolute path. filepath.Join("/a", "/b") returns /b. String concatenation would produce /a//b. This behavior prevents accidental path traversal but can surprise developers who expect simple appending. The compiler rejects type mismatches, but it won't warn you about logical path errors. You'll get open /b: no such file or directory if you expected /a/b.
Convention aside: Use _ to discard values you don't need. When splitting a path, filepath.Split returns the directory and the file. If you only need the file, write _, name := filepath.Split(p). This signals that you considered the directory and chose to drop it. It's clearer than assigning to a variable you never use.
A backslash in a URL breaks the web. A forward slash in a Windows path might break the build.
Decision matrix
Use path when you are manipulating strings that represent logical paths, such as URLs, tar archive entries, or internal identifiers that must always use forward slashes.
Use path/filepath when you are interacting with the file system, including opening files, walking directories, or constructing paths that the OS needs to understand.
Use filepath.ToSlash when you need to convert an OS-specific path from filepath into a forward-slash string for use with path functions or network protocols.
Use filepath.FromSlash when you receive a forward-slash path from a network source and need to convert it to the local OS format before passing it to os functions.
File system gets filepath. Everything else gets path.