Tests the file is empty.

See Dir#empty? and FileTest#empty?.

Returns true if self points to a mountpoint.

The opposite of #absolute?

It returns false if the pathname begins with a slash.

p = Pathname.new('/im/sure')
p.relative?
  #=> false

p = Pathname.new('not/so/sure')
p.relative?
  #=> true

Predicate method for root directories. Returns true if the pathname consists of consecutive slashes.

It doesn't access the filesystem. So it may return false for some pathnames which points to roots such as /usr/...

Alias for #+.

Compares the contents of self and other as strings; see String#<=>.

Returns:

• -1 if self's string is smaller than other's string.
• 0 if the two are equal.
• 1 if self's string is larger than other's string.
• nil if other is not a Pathname.

Examples:

Pathname('a')  <=> Pathname('b')  # => -1
Pathname('a')  <=> Pathname('ab') # => -1
Pathname('a')  <=> Pathname('a')  # => 0
Pathname('b')  <=> Pathname('a')  # => 1
Pathname('ab') <=> Pathname('a')  # => 1
Pathname('ab') <=> 'a'            # => nil

Two pathnames that are different may refer to the same entry in the filesystem:

Pathname('lib') <=> Pathname('./lib') # => 1

Returns whether the stored paths in self and other are equal:

pn = Pathname('lib')
pn == Pathname('lib')   # => true
pn == Pathname('./lib') # => false

Returns false if other is not a pathname:

pn == 'lib'             # => false

Alias for #==.

add_trailing_separator(path) -> path

With a block given, yields self, then a new pathname for each successive dirname in the stored path; see File.dirname:

Pathname('/path/to/some/file.rb').ascend {|dirname| p dirname}
#<Pathname:/path/to/some/file.rb>
#<Pathname:/path/to/some>
#<Pathname:/path/to>
#<Pathname:/path>
#<Pathname:/>

With no block given, returns a new ::Enumerator.

Returns a new ::Time object containing the time of the most recent access (read or write) to the entry represented by self:

# Work in a temporary directory.
require 'tmpdir'
Dir.mktmpdir do |tmpdirpath|
# A subdirectory therein, and its Pathname.
dirpath = File.join(tmpdirpath, 'subdir')
Dir.mkdir(dirpath)
dir_pn = Pathname(dirpath)
puts "Create directory; establishes atime for directory."
puts "  Directory atime: #{dir_pn.atime}"
sleep(1)

# A file in the subdirectory, and its Pathname.
filepath = File.join(dirpath, 't.txt')
puts "Create file; establishes atime for file, updates atime for directory."
File.write(filepath, 'foo')
file_pn = Pathname(filepath)
puts "  File atime:      #{file_pn.atime}"
puts "  Directory atime: #{dir_pn.atime}"
sleep(1)
puts "Write file; updates atimes for file and directory."
File.write(filepath, 'bar')
puts "  File atime:      #{file_pn.atime}"
puts "  Directory atime: #{dir_pn.atime}"
end

Output:

Create directory; establishes atime for directory.
Directory atime: 2026-05-14 14:36:43 +0100
Create file; establishes atime for file, updates atime for directory.
File atime:      2026-05-14 14:36:44 +0100
Directory atime: 2026-05-14 14:36:44 +0100
Write file; updates atimes for file and directory.
File atime:      2026-05-14 14:36:45 +0100
Directory atime: 2026-05-14 14:36:45 +0100

See {File System Timestamps}.

Returns a new Pathname object containing all or part of the last entry of the path represented by self. Entries are delimited by the value of constant File::SEPARATOR and, if non-nil, the value of constant File::ALT_SEPARATOR.

When suffix is the empty string '', returns all of the last entry:

Pathname.new('foo/bar/baz/bat.txt').basename # => #<Pathname:bat.txt>
Pathname.new('foo/bar/baz').basename         # => #<Pathname:baz>

File::SEPARATOR                              # => "/"
Pathname.new('foo/bar.txt////').basename     # => #<Pathname:bar.txt>
File::ALT_SEPARATOR # => "\\"                # On Windows.
Pathname.new('foo/bar.txt//\\\\//').basename # => #<Pathname:bar.txt>

When suffix is '.*', the last filename extension, if any, is removed:

Pathname.new('foo/bar.txt').basename('.*')     # => #<Pathname:bar>
Pathname.new('foo/bar.txt.old').basename('.*') # => #<Pathname:bar.txt>
Pathname.new('foo/bar').basename('.*')         # => #<Pathname:bar>

When suffix is any string other than '' or '.*', the matching trailing substring, if any, is removed:

Pathname.new('foo/bar.txt').basename('.txt') # => #<Pathname:bar>
Pathname.new('foo/bar.txt').basename('txt')  # => #<Pathname:bar.>
Pathname.new('foo/bar.txt').basename('*')    # => #<Pathname:bar.txt>
Pathname.new('foo/bar.txt').basename('.')    # => #<Pathname:bar.txt>

Behaves like #read, except that the file is opened in binary mode with ASCII-8BIT encoding.

Behaves like #write, except that the file is opened in binary mode with ASCII-8BIT encoding.

Returns a new ::Time object containing the create time of the entry represented by self:

#### Work in a temporary directory.
Pathname.mktmpdir do |tmpdirpath|
  # A subdirectory therein, and its Pathname.
  dirpath = File.join(tmpdirpath, 'subdir')
  dir_pn = Pathname(dirpath)
  puts "Create directory; directory birthtime established."
  dir_pn.mkdir
  puts "  Directory birthtime: #{dir_pn.birthtime}"
  sleep(1)

  # A file in the subdirectory, and its Pathname.
  filepath = File.join(dirpath, 't.txt')
  file_pn = Pathname(filepath)
  puts "Create file; file birthtime established; directory birthtime not updated."
  file_pn.write('foo')
  puts "  File birthtime:      #{file_pn.birthtime}"
  puts "  Directory birthtime: #{dir_pn.birthtime}"
  sleep(1)
  puts "Write file; neither birthtime updated."
  file_pn.write('bar')
  puts "  File birthtime:      #{file_pn.birthtime}"
  puts "  Directory birthtime: #{dir_pn.birthtime}"
end

Output:

Create directory; directory birthtime established.
  Directory birthtime: 2026-05-14 23:41:12 +0100
Create file; file birthtime established; directory birthtime not updated.
  File birthtime:      2026-05-14 23:41:13 +0100
  Directory birthtime: 2026-05-14 23:41:12 +0100
Write file; neither birthtime updated.
  File birthtime:      2026-05-14 23:41:13 +0100
  Directory birthtime: 2026-05-14 23:41:12 +0100

See File System Timestamps.

Returns whether self represents a path to a block device (i.e., a direct-access device):

Pathname('/dev/nvme0n1').blockdev? # => true
Pathname('/dev/loop0').blockdev?   # => true
Pathname('/dev/tty').blockdev?     # => false
Pathname('/dev/null').blockdev?    # => false
Pathname('nosuch').blockdev?       # => false
Pathname($stdin).blockdev?         # => false

The returned value is OS-dependent; on Windows, almost always false.

Returns whether self represents a path to a character device (i.e., a sequential-access device):

Pathname('/dev/tty').chardev?     # => true
Pathname('/dev/null').chardev?    # => true
Pathname('/dev/nvme0n1').chardev? # => false
Pathname('/dev/loop0').chardev?   # => false
Pathname($stdin).chardev?         # => false
Pathname('nosuch').chardev?       # => false

The returned value is OS-dependent; on Windows, almost always false.

Returns an array of pathnames; each represents a child of the entry represented by self, which must be an existing directory in the underlying file system.

With with_dirnames given as true (the default), each pathname contains the full entry:

Pathname('lib').children.size # => 72
Pathname('lib').children.take(3)
#### => [#<Pathname:lib/bundled_gems.rb>, #<Pathname:lib/bundler>, #<Pathname:lib/bundler.rb>]

With with_dirnames given as false, each pathname contains only the basename of the entry:

Pathname('lib').children(false).take(3)
#### => [#<Pathname:bundled_gems.rb>, #<Pathname:bundler>, #<Pathname:bundler.rb>]

Note that entries . and .. in directory are not actually children, and so are never included in the result.

Changes the mode (i.e., permissions) of the entry represented by self; see {File Permissions}; returns 1:

#### A helper method to make an integer mode display as octal.
def pretty(mode); '0' + (mode & 0777).to_s(8); end

#### Work in a temporary directory.
Pathname.mktmpdir do |tmpdirpath|
  # A subdirectory therein, and its Pathname.
  dirpath = File.join(tmpdirpath, 'subdir')
  dir_pn = Pathname(dirpath)
  dir_pn.mkdir
  # The directory mode.
  puts "Original directory mode: #{pretty(dir_pn.stat.mode)}"
  # Change the directory mode.
  dir_pn.chmod(0777)
  puts "New directory mode:      #{pretty(dir_pn.stat.mode)}"

  # A file in the subdirectory, and its Pathname.
  filepath = File.join(dirpath, 't.txt')
  file_pn = Pathname(filepath)
  # Create the file.
  file_pn.write('foo')
  # The file mode.
  puts "Original file mode:      #{pretty(file_pn.stat.mode)}"
  # Change the file modes.
  file_pn.chmod(0777)
  puts "New file mode:           #{pretty(file_pn.stat.mode)}"
end

Output:

Original directory mode: 0775
New directory mode:      0777
Original file mode:      0664
New file mode:           0777

chop_basename(path) -> [pre-basename, basename] or nil

Changes the owner and group of an entry (directory or file):

#### Work in a temporary directory.
Pathname.mktmpdir do |tmpdirpath|
  # A subdirectory therein, and its Pathname.
  dirpath = File.join(tmpdirpath, 'subdir')
  dir_pn = Pathname(dirpath)
  dir_pn.mkdir
  dir_stat = File.stat(dirpath)
  puts "Original directory owner: #{dir_stat.uid}"
  puts "Original directory group: #{dir_stat.gid}"
  dir_pn.chown(1000, 1000)
  dir_stat = File.stat(dirpath)
  puts "New directory owner:      #{dir_stat.uid}"
  puts "New directory group:      #{dir_stat.gid}"

  # A file in the subdirectory, and its Pathname.
  filepath = File.join(dirpath, 't.txt')
  file_pn = Pathname(filepath)
  # Create the file.
  file_pn.write('foo')
  file_stat = File.stat(filepath)
  puts "Original file owner:      #{file_stat.uid}"
  puts "Original file group:      #{file_stat.gid}"
  file_pn = Pathname(dirpath)
  file_pn.chown(1000, 1000)
  file_stat = File.stat(dirpath)
  puts "New file owner:           #{file_stat.uid}"
  puts "New file group:           #{file_stat.gid}"
end

Output:

Original directory owner: 0
Original directory group: 0
New directory owner:      1000
New directory group:      1000
Original file owner:      0
Original file group:      0
New file owner:           1000
New file group:           1000

Notes:

• On Windows, the owner and group are not changed.
• Only a process with superuser privileges can change the owner of an entry.
• The owner of an entry can change its group to any group to which the owner belongs.
• A nil or -1 owner or group id is ignored.
• The method follows symbolic links to the target entry.

Returns a new Pathname object, "cleaned" of unnecessary separators, single-dot entries, and double-dot entries.

When self is empty, returns a pathname with a single-dot entry:

Pathname('').cleanpath # => {#<}Pathname:.>

Separators

A lone separator is preserved:

Pathname('/').cleanpath # => {#<}Pathname:/>

Multiple trailing separators are removed:

Pathname('foo/////').cleanpath # => {#<}Pathname:foo>
Pathname('foo/').cleanpath     # => {#<}Pathname:foo>

Multiple embedded separators are reduced to a single separator:

Pathname('foo///bar').cleanpath # => {#<}Pathname:foo/bar>

Multiple leading separators are reduced:

#### On Windows, where {File.dirname}('//') == '//'.
Pathname('/////foo').cleanpath # => {#<}Pathname://foo>
Pathname('/////').cleanpath    # => {#<}Pathname://>
#### Otherwise, where {File.dirname}('//') == '/'.
Pathname('/////foo').cleanpath # => {#<}Pathname:/foo>
Pathname('/////').cleanpath    # => {#<}Pathname:/>

Single-Dot Entries

A lone single-dot entry is preserved:

Pathname('.').cleanpath  # => {#<}Pathname:.>

A non-lone single-dot entry, regardless of its location, is removed:

Pathname('foo/././././bar').cleanpath  # => {#<}Pathname:foo/bar>
Pathname('./foo/./././bar').cleanpath  # => {#<}Pathname:foo/bar>
Pathname('foo/./././bar/./').cleanpath # => {#<}Pathname:foo/bar>

Double-Dot Entries

A lone double-dot entry is preserved:

Pathname('..').cleanpath # => {#<}Pathname:..>

When a non-lone double-dot entry is preceded by a named entry, both are removed:

Pathname('foo/..').cleanpath          # => {#<}Pathname:.>
Pathname('foo/../bar').cleanpath      # => {#<}Pathname:bar>
Pathname('foo/../bar/..').cleanpath   # => {#<}Pathname:.>
Pathname('foo/bar/./../..').cleanpath # => {#<}Pathname:.>

When a non-lone double-dot entry is not preceded by a named entry, it is preserved:

Pathname('../..').cleanpath # => {#<}Pathname:../..>

A non-lone meaningless double-dot entry is removed:

Pathname('/..').cleanpath    # => {#<}Pathname:/>
Pathname('/../..').cleanpath # => {#<}Pathname:/>

Symbolic Links

If the path may contain symbolic links, consider give optional argument symlinks as true; the method then uses a more conservative algorithm that avoids breaking symbolic links. This may preserve more double-dot entries than are absolutely necessary, but without accessing the filesystem, this can't be avoided.

Examples:

Pathname('a/').cleanpath           # => {#<}Pathname:a>
Pathname('a/').cleanpath(true)     # => {#<}Pathname:a/>

Pathname('a/.').cleanpath          # => {#<}Pathname:a>
Pathname('a/.').cleanpath(true)    # => {#<}Pathname:a/.>

Pathname('a/./').cleanpath         # => {#<}Pathname:a>
Pathname('a/./').cleanpath(true)   # => {#<}Pathname:a/.>

Pathname('a/b/.').cleanpath        # => {#<}Pathname:a/b>
Pathname('a/b/.').cleanpath(true)  # => {#<}Pathname:a/b/.>

Pathname('a/../.').cleanpath       # => {#<}Pathname:.>
Pathname('a/../.').cleanpath(true) # => {#<}Pathname:a/..>

Pathname('a/b/../../../../c/../d').cleanpath
#### => {#<}Pathname:../../d>
Pathname('a/b/../../../../c/../d').cleanpath(true)
#### => {#<}Pathname:a/b/../../../../c/../d>

Clean the path simply by resolving and removing excess . and .. entries. Nothing more, nothing less.

See File.ctime. Returns last (directory entry, not file) change time.

Alias for #unlink.

Iterates over and yields a new Pathname object for each element in the given path in descending order.

Pathname.new('/path/to/some/file.rb').descend {|v| p v} #Pathname:/ #Pathname:/path #Pathname:/path/to #Pathname:/path/to/some #Pathname:/path/to/some/file.rb

Pathname.new('path/to/some/file.rb').descend {|v| p v} #Pathname:path #Pathname:path/to #Pathname:path/to/some #Pathname:path/to/some/file.rb

Returns an ::Enumerator if no block was given.

enum = Pathname.new("/usr/bin/ruby").descend
# ... do stuff ...
enum.each { |e| ... }
# yields Pathnames /, /usr, /usr/bin, and /usr/bin/ruby.

It doesn't access the filesystem.

See FileTest#directory?.

See File.dirname. Returns all but the last component of the path.

Iterates over the children of the directory (files and subdirectories, not recursive).

It yields Pathname object for each child.

By default, the yielded pathnames will have enough information to access the files.

If you set with_directory to false, then the returned pathnames will contain the filename only.

Pathname("/usr/local").each_child {|f| p f }
#=> #<Pathname:/usr/local/share>
#   #<Pathname:/usr/local/bin>
#   #<Pathname:/usr/local/games>
#   #<Pathname:/usr/local/lib>
#   #<Pathname:/usr/local/include>
#   #<Pathname:/usr/local/sbin>
#   #<Pathname:/usr/local/src>
#   #<Pathname:/usr/local/man>

Pathname("/usr/local").each_child(false) {|f| p f }
#=> #<Pathname:share>
#   #<Pathname:bin>
#   #<Pathname:games>
#   #<Pathname:lib>
#   #<Pathname:include>
#   #<Pathname:sbin>
#   #<Pathname:src>
#   #<Pathname:man>

Note that the results never contain the entries . and .. in the directory because they are not children.

See #children

Iterates over the entries (files and subdirectories) in the directory. It yields a Pathname object for each entry.

This method has existed since 1.8.1.

Iterates over each component of the path.

Pathname.new("/usr/bin/ruby").each_filename {|filename| ... }
# yields "usr", "bin", and "ruby".

Returns an ::Enumerator if no block was given.

enum = Pathname.new("/usr/bin/ruby").each_filename
# ... do stuff ...
enum.each { |e| ... }
# yields "usr", "bin", and "ruby".

#each_line iterates over the line in the file. It yields a ::String object for each line.

This method has existed since 1.8.1.

Return the entries (files and subdirectories) in the directory, each as a Pathname object.

Alias for #==.

See FileTest#executable?.

See FileTest#executable_real?.

See FileTest#exist?.

See File.expand_path.

See File.extname. Returns the file's extension.

See FileTest#file?.

See File.fnmatch. Return true if the receiver matches the given pattern.

See File.fnmatch? (same as #fnmatch).

Freze self.

See File.ftype. Returns "type" of file ("file", "directory", etc).

Returns or yields Pathname objects.

Pathname("ruby-2.4.2").glob("R*.md") #=> [#Pathname:ruby-2.4.2/README.md, #Pathname:ruby-2.4.2/README.ja.md]

See Dir.glob. This method uses the base keyword argument of Dir.glob.

See FileTest#grpowned?.

has_trailing_separator?(path) -> bool

Joins the given pathnames onto self to create a new Pathname object. This is effectively the same as using #+ to append self and all arguments sequentially.

path0 = Pathname.new("/usr")                # Pathname:/usr
path0 = path0.join("bin/ruby")              # Pathname:/usr/bin/ruby
  # is the same as
path1 = Pathname.new("/usr") + "bin/ruby"   # Pathname:/usr/bin/ruby
path0 == path1
  #=> true

See File.lchmod.

See File.lchown.

See File.lstat.

Update the access and modification times of the file.

Same as #utime, but does not follow symbolic links.

See File.lutime.

See File.link. Creates a hard link.

See File.symlink. Creates a symbolic link.

See Dir.mkdir. Create the referenced directory.

Creates a full path, including any intermediate directories that don't yet exist.

See FileUtils.mkpath and FileUtils.mkdir_p

See File.mtime. Returns last modification time.

See File.open. Opens the file for reading or writing.

See Dir.open.

See FileTest#owned?.

Returns the parent directory.

This is same as self + '..'.

See FileTest#pipe?.

(path1, path2) -> path

Reads and returns some or all of the content of the file whose path is self.to_s.

With no arguments given, reads in text mode and returns the entire content of the file:

Pathname.new('t.txt').read
# => "First line\nSecond line\n\nFourth line\nFifth line\n"
Pathname.new('t.ja').read
# => "こんにちは"
Pathname.new('t.dat').read
# => "\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"

On Windows, text mode can terminate reading and leave bytes in the file unread when encountering certain special bytes. Consider using #binread if all bytes in the file should be read.

With argument length given, returns length bytes if available:

Pathname.new('t.txt').read(7)
# => "First l"
Pathname.new('t.ja').read(7)
# => "\xE3\x81\x93\xE3\x82\x93\xE3"
Pathname.new('t.dat').read(7)
# => "\xFE\xFF\x99\x90\x99\x91\x99"

Returns all bytes if length is larger than the files size:

Pathname.new('t.txt').read(700)
# => "First line\r\nSecond line\r\n\r\nFourth line\r\nFifth line\r\n"
Pathname.new('t.ja').read(700)
# => "\xE3\x81\x93\xE3\x82\x93\xE3\x81\xAB\xE3\x81\xA1\xE3\x81\xAF"
Pathname.new('t.dat').read(700)
# => "\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"

With arguments length and offset given, returns length bytes if available, beginning at the given offset:

Pathname.new('t.txt').read(10, 2)
# => "rst line\r\n"
Pathname.new('t.ja').read(10, 2)
# => "\x93\xE3\x82\x93\xE3\x81\xAB\xE3\x81\xA1"
Pathname.new('t.dat').read(10, 2)
# => "\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"

Returns nil if offset is past the end of the file:

Pathname.new('t.txt').read(10, 200) # => nil

Optional keyword arguments opts specify:

• Open Options.
• {Encoding options}.

See FileTest#readable?.

See FileTest#readable_real?.

See File.readlines. Returns all the lines from the file.

See File.readlink. Read symbolic link.

Returns the real (absolute) pathname of self in the actual filesystem.

Does not contain symlinks or useless dots, .. and ..

The last component of the real pathname can be nonexistent.

Returns the real (absolute) pathname for self in the actual filesystem.

Does not contain symlinks or useless dots, .. and ..

All components of the pathname must exist when this method is called.

Returns a relative path from the given base_directory to the receiver.

If self is absolute, then base_directory must be absolute too.

If self is relative, then base_directory must be relative too.

This method doesn't access the filesystem. It assumes no symlinks.

::ArgumentError is raised when it cannot find a relative path.

Note that this method does not handle situations where the case sensitivity of the filesystem in use differs from the operating system default.

See File.rename. Rename the file.

See Dir.rmdir. Remove the referenced directory.

See FileTest#setgid?.

See FileTest#setuid?.

See FileTest#size.

See FileTest#size?.

See FileTest#socket?.

See File.split. Returns the #dirname and the #basename in an ::Array.

split_names(path) -> prefix, [name, ...]

See File.stat. Returns a ::File::Stat object.

See FileTest#sticky?.

Return a pathname which is substituted by String#sub.

path1 = Pathname.new('/usr/bin/perl')
path1.sub('perl', 'ruby')
    #=> #<Pathname:/usr/bin/ruby>

Return a pathname with repl added as a suffix to the basename.

If self has no extension part, repl is appended.

Pathname.new('/usr/bin/shutdown').sub_ext('.rb')
    #=> #<Pathname:/usr/bin/shutdown.rb>

See FileTest#symlink?.

See File.sysopen.

Alias for #to_s.

Return the path as a ::String.

See File.truncate. Truncate the file to length bytes.

Removes a file or directory, using File.unlink or Dir.unlink as necessary.

See File.utime. Update the access and modification times.

See FileTest#world_readable?.

See FileTest#world_writable?.

See FileTest#writable?.

See FileTest#writable_real?.

Opens the file at self.to_s, writes the given data to it, and closes the file; returns the number of bytes written.

With only argument data given, writes the given data to the file:

path = 't.tmp'
pn = Pathname.new(path)
pn.write('foo') # => 3
File.read(path) # => "foo"

If offset is zero (the default), the file is overwritten:

pn.write('bar')
File.read(path) # => "bar"

If offset in within the file content, the file is partly overwritten:

pn.write('foobarbaz')
pn.write('BAR', 3)
File.read(path) # => "fooBARbaz"

If offset is outside the file content, the file is padded with null characters "\u0000":

pn.write('bat', 12)
File.read(path) # => "fooBARbaz\u0000\u0000\u0000bat"

Optional keyword arguments opts specify:

• Open Options.
• {Encoding options}.

See FileTest#zero?.